@proofchain/sdk 2.15.0 → 2.17.0

package/dist/index.d.mts

@@ -1858,6 +1858,7 @@ interface UserReward {
     id: string;
     reward_name: string;
     reward_type: string;
+    category?: string;
     slug?: string;
     description?: string;
     status: string;
@@ -1914,6 +1915,23 @@ interface ManualRewardRequest {
     trigger_data?: Record<string, any>;
     distribute_immediately?: boolean;
 }
+interface ClaimNFTResult {
+    success: boolean;
+    reward_id: string;
+    token_id?: number;
+    tx_hash: string;
+    wallet_address: string;
+}
+interface DistributeResult {
+    success: boolean;
+    reward_id: string;
+    message: string;
+}
+interface RevokeResult {
+    success: boolean;
+    reward_id: string;
+    status: string;
+}
 interface ListRewardsOptions {
     is_active?: boolean;
     reward_type?: string;
@@ -1962,37 +1980,108 @@ declare class RewardsClient {
         offset?: number;
     }): Promise<EarnedReward[]>;
     /**
-     * Get earned rewards for a user (with full badge/reward details)
+     * Get earned rewards for a user (with full badge/reward details).
+     * Use this to display a user's reward collection on a dedicated screen.
+     *
+     * @example
+     * ```ts
+     * // All user rewards
+     * const all = await client.rewards.getUserRewards('user-123');
+     *
+     * // Only badges in the "Fan Pass" category
+     * const badges = await client.rewards.getUserRewards('user-123', {
+     *   reward_type: 'badge',
+     *   category: 'Fan Pass',
+     * });
+     *
+     * // Only distributed rewards
+     * const distributed = await client.rewards.getUserRewards('user-123', {
+     *   status: 'distributed',
+     * });
+     * ```
      */
     getUserRewards(userId: string, options?: {
         status?: string;
         reward_type?: string;
+        category?: string;
     }): Promise<UserReward[]>;
     /**
-     * Get the public reward catalog (active, public reward definitions)
+     * Get the public reward catalog (active, public reward definitions).
      * Available to both API key and end-user JWT clients.
+     *
+     * @param category - Optional category filter (e.g. "Fan Pass", "Partner: Acme")
+     *
+     * @example
+     * ```ts
+     * // All available rewards
+     * const all = await client.rewards.getCatalog();
+     *
+     * // Only "Fan Pass" rewards
+     * const fanPass = await client.rewards.getCatalog('Fan Pass');
+     * ```
      */
-    getCatalog(): Promise<RewardDefinition[]>;
+    getCatalog(category?: string): Promise<RewardDefinition[]>;
     /**
      * Claim a lazy-minted NFT reward.
      * The wallet_address receives the minted NFT. The tenant's treasury pays gas.
      * Available to both API key and end-user JWT clients (scoped to own rewards).
+     *
+     * For non-NFT rewards, use {@link distribute} instead.
      */
-    claimReward(earnedRewardId: string, walletAddress: string): Promise<{
-        success: boolean;
-        reward_id: string;
-        token_id?: number;
-        tx_hash: string;
-        wallet_address: string;
-    }>;
+    claimNFT(earnedRewardId: string, walletAddress: string): Promise<ClaimNFTResult>;
+    /**
+     * @deprecated Use {@link claimNFT} instead — this method only works for lazy-mint NFTs.
+     */
+    claimReward(earnedRewardId: string, walletAddress: string): Promise<ClaimNFTResult>;
     /**
-     * Manually award rewards to users
+     * Manually award rewards to one or more users.
+     * Works for all reward types: points, tokens, NFTs, badges, custom.
+     *
+     * @example
+     * ```ts
+     * // Award a badge to two users
+     * const rewards = await client.rewards.award({
+     *   definition_id: 'badge-def-id',
+     *   user_ids: ['user-1', 'user-2'],
+     *   distribute_immediately: true,
+     * });
+     * ```
+     */
+    award(request: ManualRewardRequest): Promise<EarnedReward[]>;
+    /**
+     * @deprecated Use {@link award} instead.
      */
     awardManual(request: ManualRewardRequest): Promise<EarnedReward[]>;
     /**
-     * Distribute pending rewards (mint NFTs, transfer tokens)
+     * Distribute a pending or failed reward.
+     * Works for all reward types — triggers the appropriate distribution
+     * (mint NFT, transfer tokens, issue badge, credit points, etc.).
+     *
+     * @example
+     * ```ts
+     * // Distribute a pending reward
+     * const result = await client.rewards.distribute('earned-reward-id');
+     * ```
+     */
+    distribute(earnedRewardId: string): Promise<DistributeResult>;
+    /**
+     * @deprecated Use {@link distribute} instead.
+     */
+    distributePending(earnedRewardId: string): Promise<DistributeResult>;
+    /**
+     * Distribute all pending rewards for the tenant.
+     * Queues every pending reward for background distribution.
+     */
+    distributeAll(): Promise<{
+        queued: number;
+    }>;
+    /**
+     * Revoke an earned reward.
+     *
+     * @param earnedRewardId - The earned reward ID to revoke
+     * @param reason - Reason for revocation
      */
-    distributePending(earnedRewardId: string): Promise<EarnedReward>;
+    revoke(earnedRewardId: string, reason: string): Promise<RevokeResult>;
     /**
      * Upload an asset for a reward (image, metadata JSON)
      */
@@ -2859,6 +2948,94 @@ declare class FanpassLeaderboardClient {
     }): Promise<FanpassUserComparisonResponse>;
 }
 
+/**
+ * Notifications Client
+ *
+ * Provides real-time notification streaming via Server-Sent Events (SSE).
+ * Notifications are pushed from the backend when quest/reward events occur.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to notifications
+ * const unsub = client.notifications.subscribe('user-123', (event) => {
+ *   switch (event.event) {
+ *     case 'quest_step_completed':
+ *       showToast(`Step completed: ${event.data.step_name}`);
+ *       break;
+ *     case 'quest_completed':
+ *       showToast(`Quest completed: ${event.data.quest_name}!`);
+ *       break;
+ *     case 'badge_earned':
+ *       showBadgeModal(event.data);
+ *       break;
+ *     case 'reward_claimable':
+ *       showClaimButton(event.data);
+ *       break;
+ *   }
+ * });
+ *
+ * // Later, unsubscribe
+ * unsub();
+ * ```
+ */
+
+/** Notification event types pushed by the server. */
+type NotificationEventType = 'connected' | 'quest_step_completed' | 'quest_completed' | 'reward_earned' | 'reward_distributed' | 'reward_claimable' | 'points_awarded' | 'badge_earned' | 'level_up';
+/** A notification event received from the SSE stream. */
+interface NotificationEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event type */
+    event: NotificationEventType;
+    /** Event-specific payload */
+    data: Record<string, any>;
+    /** Tenant ID */
+    tenant_id: string;
+    /** User ID */
+    user_id: string;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/** Callback invoked for each notification event. */
+type NotificationCallback = (event: NotificationEvent) => void;
+/** Options for the subscribe method. */
+interface SubscribeOptions {
+    /** Called when the connection is established */
+    onConnect?: () => void;
+    /** Called when the connection is lost (will auto-reconnect) */
+    onDisconnect?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Auto-reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms (default: 3000) */
+    reconnectDelay?: number;
+}
+/** Function to call to unsubscribe / close the SSE connection. */
+type Unsubscribe = () => void;
+declare class NotificationsClient {
+    private baseUrl;
+    private authHeaders;
+    constructor(http: HttpClient);
+    /**
+     * Subscribe to real-time notifications for a user.
+     *
+     * Opens a Server-Sent Events connection and calls the callback
+     * for each notification event (quest progress, rewards, etc.).
+     *
+     * Returns an unsubscribe function to close the connection.
+     *
+     * **Browser usage:** Works out of the box with EventSource.
+     * **Node.js usage:** Requires the `eventsource` package.
+     *
+     * @param userId - The external user ID to subscribe for
+     * @param callback - Function called for each notification event
+     * @param options - Connection options (reconnect, callbacks)
+     * @returns Unsubscribe function to close the connection
+     */
+    subscribe(userId: string, callback: NotificationCallback, options?: SubscribeOptions): Unsubscribe;
+}
+
 /**
  * ProofChain Client
  */
@@ -3053,6 +3230,8 @@ declare class ProofChain {
     cohorts: CohortLeaderboardClient;
     /** Fanpass leaderboard client for composite score leaderboards */
     fanpassLeaderboard: FanpassLeaderboardClient;
+    /** Notifications client for real-time SSE streaming */
+    notifications: NotificationsClient;
     constructor(options: ProofChainOptions);
     /**
      * Create a client for end-user JWT authentication (PWA/frontend use).
@@ -3268,4 +3447,4 @@ declare class TimeoutError extends ProofChainError {
     constructor(message?: string);
 }
 
-export { type Achievement, type ActivitySummaryView, type AddNFTRequest, type ApiKey, type AttestRequest, type AttestationMode, type AttestationResult, AuthenticationError, AuthorizationError, type AvailableView, type Badge, type BatchIngestRequest, type BatchIngestResponse, type BatchVerifyResult, type BlockchainProof, type BlockchainStats, type Certificate, type CertificateVerifyResult, CertificatesResource, type Channel, type ChannelState, type ChannelStatus, ChannelsResource, type ClaimRewardResult, type CohortDefinition, type CohortGroupStats, CohortLeaderboardClient, type CohortLeaderboardEntry, type CohortLeaderboardOptions, type CohortLeaderboardResponse, type ComprehensiveWalletInfo, type CreateAchievementRequest, type CreateApiKeyRequest, type CreateBadgeRequest, type CreateChannelRequest, type CreateDataViewRequest, type CreateDualWalletsRequest, type CreateEndUserRequest, type CreateEventRequest, type CreatePassportDefinitionRequest, type CreatePassportRequest, type CreateQuestRequest, type CreateQuestStepRequest, type CreateRewardDefinitionRequest, type CreateSchemaRequest, type CreateTemplateFieldRequest, type CreateTemplateRequest, type CreateWalletRequest as CreateUserWalletRequest, type CreateWalletRequest$1 as CreateWalletRequest, type CreateWebhookRequest, type DataViewColumn, type DataViewComputation, type DataViewDetail, type DataViewExecuteResult, type DataViewInfo, type DataViewListResponse, type DataViewPreviewRequest, type DataViewPreviewResult, type DataViewSummary, DataViewsClient, DocumentsResource, type DualWallets, type EarnedReward, type EndUser, EndUserIngestionClient, type EndUserIngestionClientOptions, type EndUserListResponse, EndUsersClient, type Event, type EventBatchProof, type EventMetadata, type EventStatus, EventsResource, type ExecuteSwapRequest, type Facet, type FacetsResponse, type FanProfileView, type FanpassGroupStats, FanpassLeaderboardClient, type FanpassLeaderboardEntry, type FanpassLeaderboardOptions, type FanpassLeaderboardResponse, type FanpassUserComparisonResponse, type FieldValue, type GDPRDeletionRequest, type GDPRDeletionResponse, type GDPRPreviewResponse, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LeaderboardUserProfile$1 as LeaderboardUserProfile, type LinkWalletRequest, type ListCertificatesRequest, type ListCohortsOptions, type ListEndUsersOptions, type ListEventsRequest, type ListQuestsOptions, type ListRewardsOptions, type ListSchemasOptions, type ManualRewardRequest, type MergeUsersRequest, type Milestone, type NFT, NetworkError, NotFoundError, type Passport, PassportClient, type PassportDefinition, type PassportFieldValue, type PassportHistory, type PassportTemplate, type PassportV2Data, type PassportWithFields, ProofChain, ProofChainError, type ProofChainOptions, type ProofVerifyResult, type Quest, type QuestStep, type QuestWithProgress, QuestsClient, RateLimitError, type RegisterWalletRequest, type RewardAsset, type RewardDefinition, type RewardEarned, RewardsClient, type Schema, type SchemaDetail, type SchemaField, type SchemaListResponse, type ValidationError$1 as SchemaValidationError, SchemasClient, type SearchFilters, type SearchQueryRequest, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type SearchStats, ServerError, type SetProfileRequest, type Settlement, type StepCompletionResult, type StepProgress, type StreamAck, type StreamEventRequest, type SwapQuote, type SwapQuoteRequest, type SwapResult, type TemplateField, type TenantInfo, TenantResource, type TierDefinition, TimeoutError, type TokenBalance, type TransferRequest, type TransferResult, type UpdateDataViewRequest, type UpdateEndUserRequest, type UpdatePassportRequest, type UpdateWebhookRequest, type UsageStats, type UserAchievement, type UserActivity, type UserActivityResponse, type UserBadge, type UserBreakdownResponse, type UserCohortBreakdownEntry, type UserQuestProgress, type UserReward$1 as UserReward, type UserRewardsResponse, type UserWalletSummary, type UserWithWallets, type UsersWithWalletsResponse, type ValidateDataRequest, ValidationError, type ValidationErrorDetail, type ValidationResult, type VaultFile, type VaultFolder, type VaultListResponse, VaultResource, type VaultStats, type VaultUploadRequest, type VerificationResult, VerifyResource, type ViewColumn, type ViewTemplate, type Wallet, type WalletBalance, WalletClient, type WalletCreationResult, type WalletStats, type Webhook, WebhooksResource };
+export { type Achievement, type ActivitySummaryView, type AddNFTRequest, type ApiKey, type AttestRequest, type AttestationMode, type AttestationResult, AuthenticationError, AuthorizationError, type AvailableView, type Badge, type BatchIngestRequest, type BatchIngestResponse, type BatchVerifyResult, type BlockchainProof, type BlockchainStats, type Certificate, type CertificateVerifyResult, CertificatesResource, type Channel, type ChannelState, type ChannelStatus, ChannelsResource, type ClaimNFTResult, type ClaimRewardResult, type CohortDefinition, type CohortGroupStats, CohortLeaderboardClient, type CohortLeaderboardEntry, type CohortLeaderboardOptions, type CohortLeaderboardResponse, type ComprehensiveWalletInfo, type CreateAchievementRequest, type CreateApiKeyRequest, type CreateBadgeRequest, type CreateChannelRequest, type CreateDataViewRequest, type CreateDualWalletsRequest, type CreateEndUserRequest, type CreateEventRequest, type CreatePassportDefinitionRequest, type CreatePassportRequest, type CreateQuestRequest, type CreateQuestStepRequest, type CreateRewardDefinitionRequest, type CreateSchemaRequest, type CreateTemplateFieldRequest, type CreateTemplateRequest, type CreateWalletRequest as CreateUserWalletRequest, type CreateWalletRequest$1 as CreateWalletRequest, type CreateWebhookRequest, type DataViewColumn, type DataViewComputation, type DataViewDetail, type DataViewExecuteResult, type DataViewInfo, type DataViewListResponse, type DataViewPreviewRequest, type DataViewPreviewResult, type DataViewSummary, DataViewsClient, type DistributeResult, DocumentsResource, type DualWallets, type EarnedReward, type EndUser, EndUserIngestionClient, type EndUserIngestionClientOptions, type EndUserListResponse, EndUsersClient, type Event, type EventBatchProof, type EventMetadata, type EventStatus, EventsResource, type ExecuteSwapRequest, type Facet, type FacetsResponse, type FanProfileView, type FanpassGroupStats, FanpassLeaderboardClient, type FanpassLeaderboardEntry, type FanpassLeaderboardOptions, type FanpassLeaderboardResponse, type FanpassUserComparisonResponse, type FieldValue, type GDPRDeletionRequest, type GDPRDeletionResponse, type GDPRPreviewResponse, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LeaderboardUserProfile$1 as LeaderboardUserProfile, type LinkWalletRequest, type ListCertificatesRequest, type ListCohortsOptions, type ListEndUsersOptions, type ListEventsRequest, type ListQuestsOptions, type ListRewardsOptions, type ListSchemasOptions, type ManualRewardRequest, type MergeUsersRequest, type Milestone, type NFT, NetworkError, NotFoundError, type NotificationCallback, type NotificationEvent, type NotificationEventType, NotificationsClient, type Passport, PassportClient, type PassportDefinition, type PassportFieldValue, type PassportHistory, type PassportTemplate, type PassportV2Data, type PassportWithFields, ProofChain, ProofChainError, type ProofChainOptions, type ProofVerifyResult, type Quest, type QuestStep, type QuestWithProgress, QuestsClient, RateLimitError, type RegisterWalletRequest, type RevokeResult, type RewardAsset, type RewardDefinition, type RewardEarned, RewardsClient, type Schema, type SchemaDetail, type SchemaField, type SchemaListResponse, type ValidationError$1 as SchemaValidationError, SchemasClient, type SearchFilters, type SearchQueryRequest, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type SearchStats, ServerError, type SetProfileRequest, type Settlement, type StepCompletionResult, type StepProgress, type StreamAck, type StreamEventRequest, type SubscribeOptions, type SwapQuote, type SwapQuoteRequest, type SwapResult, type TemplateField, type TenantInfo, TenantResource, type TierDefinition, TimeoutError, type TokenBalance, type TransferRequest, type TransferResult, type Unsubscribe, type UpdateDataViewRequest, type UpdateEndUserRequest, type UpdatePassportRequest, type UpdateWebhookRequest, type UsageStats, type UserAchievement, type UserActivity, type UserActivityResponse, type UserBadge, type UserBreakdownResponse, type UserCohortBreakdownEntry, type UserQuestProgress, type UserReward$1 as UserReward, type UserRewardsResponse, type UserWalletSummary, type UserWithWallets, type UsersWithWalletsResponse, type ValidateDataRequest, ValidationError, type ValidationErrorDetail, type ValidationResult, type VaultFile, type VaultFolder, type VaultListResponse, VaultResource, type VaultStats, type VaultUploadRequest, type VerificationResult, VerifyResource, type ViewColumn, type ViewTemplate, type Wallet, type WalletBalance, WalletClient, type WalletCreationResult, type WalletStats, type Webhook, WebhooksResource };

package/dist/index.d.ts

@@ -1858,6 +1858,7 @@ interface UserReward {
     id: string;
     reward_name: string;
     reward_type: string;
+    category?: string;
     slug?: string;
     description?: string;
     status: string;
@@ -1914,6 +1915,23 @@ interface ManualRewardRequest {
     trigger_data?: Record<string, any>;
     distribute_immediately?: boolean;
 }
+interface ClaimNFTResult {
+    success: boolean;
+    reward_id: string;
+    token_id?: number;
+    tx_hash: string;
+    wallet_address: string;
+}
+interface DistributeResult {
+    success: boolean;
+    reward_id: string;
+    message: string;
+}
+interface RevokeResult {
+    success: boolean;
+    reward_id: string;
+    status: string;
+}
 interface ListRewardsOptions {
     is_active?: boolean;
     reward_type?: string;
@@ -1962,37 +1980,108 @@ declare class RewardsClient {
         offset?: number;
     }): Promise<EarnedReward[]>;
     /**
-     * Get earned rewards for a user (with full badge/reward details)
+     * Get earned rewards for a user (with full badge/reward details).
+     * Use this to display a user's reward collection on a dedicated screen.
+     *
+     * @example
+     * ```ts
+     * // All user rewards
+     * const all = await client.rewards.getUserRewards('user-123');
+     *
+     * // Only badges in the "Fan Pass" category
+     * const badges = await client.rewards.getUserRewards('user-123', {
+     *   reward_type: 'badge',
+     *   category: 'Fan Pass',
+     * });
+     *
+     * // Only distributed rewards
+     * const distributed = await client.rewards.getUserRewards('user-123', {
+     *   status: 'distributed',
+     * });
+     * ```
      */
     getUserRewards(userId: string, options?: {
         status?: string;
         reward_type?: string;
+        category?: string;
     }): Promise<UserReward[]>;
     /**
-     * Get the public reward catalog (active, public reward definitions)
+     * Get the public reward catalog (active, public reward definitions).
      * Available to both API key and end-user JWT clients.
+     *
+     * @param category - Optional category filter (e.g. "Fan Pass", "Partner: Acme")
+     *
+     * @example
+     * ```ts
+     * // All available rewards
+     * const all = await client.rewards.getCatalog();
+     *
+     * // Only "Fan Pass" rewards
+     * const fanPass = await client.rewards.getCatalog('Fan Pass');
+     * ```
      */
-    getCatalog(): Promise<RewardDefinition[]>;
+    getCatalog(category?: string): Promise<RewardDefinition[]>;
     /**
      * Claim a lazy-minted NFT reward.
      * The wallet_address receives the minted NFT. The tenant's treasury pays gas.
      * Available to both API key and end-user JWT clients (scoped to own rewards).
+     *
+     * For non-NFT rewards, use {@link distribute} instead.
      */
-    claimReward(earnedRewardId: string, walletAddress: string): Promise<{
-        success: boolean;
-        reward_id: string;
-        token_id?: number;
-        tx_hash: string;
-        wallet_address: string;
-    }>;
+    claimNFT(earnedRewardId: string, walletAddress: string): Promise<ClaimNFTResult>;
+    /**
+     * @deprecated Use {@link claimNFT} instead — this method only works for lazy-mint NFTs.
+     */
+    claimReward(earnedRewardId: string, walletAddress: string): Promise<ClaimNFTResult>;
     /**
-     * Manually award rewards to users
+     * Manually award rewards to one or more users.
+     * Works for all reward types: points, tokens, NFTs, badges, custom.
+     *
+     * @example
+     * ```ts
+     * // Award a badge to two users
+     * const rewards = await client.rewards.award({
+     *   definition_id: 'badge-def-id',
+     *   user_ids: ['user-1', 'user-2'],
+     *   distribute_immediately: true,
+     * });
+     * ```
+     */
+    award(request: ManualRewardRequest): Promise<EarnedReward[]>;
+    /**
+     * @deprecated Use {@link award} instead.
      */
     awardManual(request: ManualRewardRequest): Promise<EarnedReward[]>;
     /**
-     * Distribute pending rewards (mint NFTs, transfer tokens)
+     * Distribute a pending or failed reward.
+     * Works for all reward types — triggers the appropriate distribution
+     * (mint NFT, transfer tokens, issue badge, credit points, etc.).
+     *
+     * @example
+     * ```ts
+     * // Distribute a pending reward
+     * const result = await client.rewards.distribute('earned-reward-id');
+     * ```
+     */
+    distribute(earnedRewardId: string): Promise<DistributeResult>;
+    /**
+     * @deprecated Use {@link distribute} instead.
+     */
+    distributePending(earnedRewardId: string): Promise<DistributeResult>;
+    /**
+     * Distribute all pending rewards for the tenant.
+     * Queues every pending reward for background distribution.
+     */
+    distributeAll(): Promise<{
+        queued: number;
+    }>;
+    /**
+     * Revoke an earned reward.
+     *
+     * @param earnedRewardId - The earned reward ID to revoke
+     * @param reason - Reason for revocation
      */
-    distributePending(earnedRewardId: string): Promise<EarnedReward>;
+    revoke(earnedRewardId: string, reason: string): Promise<RevokeResult>;
     /**
      * Upload an asset for a reward (image, metadata JSON)
      */
@@ -2859,6 +2948,94 @@ declare class FanpassLeaderboardClient {
     }): Promise<FanpassUserComparisonResponse>;
 }
 
+/**
+ * Notifications Client
+ *
+ * Provides real-time notification streaming via Server-Sent Events (SSE).
+ * Notifications are pushed from the backend when quest/reward events occur.
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to notifications
+ * const unsub = client.notifications.subscribe('user-123', (event) => {
+ *   switch (event.event) {
+ *     case 'quest_step_completed':
+ *       showToast(`Step completed: ${event.data.step_name}`);
+ *       break;
+ *     case 'quest_completed':
+ *       showToast(`Quest completed: ${event.data.quest_name}!`);
+ *       break;
+ *     case 'badge_earned':
+ *       showBadgeModal(event.data);
+ *       break;
+ *     case 'reward_claimable':
+ *       showClaimButton(event.data);
+ *       break;
+ *   }
+ * });
+ *
+ * // Later, unsubscribe
+ * unsub();
+ * ```
+ */
+
+/** Notification event types pushed by the server. */
+type NotificationEventType = 'connected' | 'quest_step_completed' | 'quest_completed' | 'reward_earned' | 'reward_distributed' | 'reward_claimable' | 'points_awarded' | 'badge_earned' | 'level_up';
+/** A notification event received from the SSE stream. */
+interface NotificationEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event type */
+    event: NotificationEventType;
+    /** Event-specific payload */
+    data: Record<string, any>;
+    /** Tenant ID */
+    tenant_id: string;
+    /** User ID */
+    user_id: string;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/** Callback invoked for each notification event. */
+type NotificationCallback = (event: NotificationEvent) => void;
+/** Options for the subscribe method. */
+interface SubscribeOptions {
+    /** Called when the connection is established */
+    onConnect?: () => void;
+    /** Called when the connection is lost (will auto-reconnect) */
+    onDisconnect?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Auto-reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms (default: 3000) */
+    reconnectDelay?: number;
+}
+/** Function to call to unsubscribe / close the SSE connection. */
+type Unsubscribe = () => void;
+declare class NotificationsClient {
+    private baseUrl;
+    private authHeaders;
+    constructor(http: HttpClient);
+    /**
+     * Subscribe to real-time notifications for a user.
+     *
+     * Opens a Server-Sent Events connection and calls the callback
+     * for each notification event (quest progress, rewards, etc.).
+     *
+     * Returns an unsubscribe function to close the connection.
+     *
+     * **Browser usage:** Works out of the box with EventSource.
+     * **Node.js usage:** Requires the `eventsource` package.
+     *
+     * @param userId - The external user ID to subscribe for
+     * @param callback - Function called for each notification event
+     * @param options - Connection options (reconnect, callbacks)
+     * @returns Unsubscribe function to close the connection
+     */
+    subscribe(userId: string, callback: NotificationCallback, options?: SubscribeOptions): Unsubscribe;
+}
+
 /**
  * ProofChain Client
  */
@@ -3053,6 +3230,8 @@ declare class ProofChain {
     cohorts: CohortLeaderboardClient;
     /** Fanpass leaderboard client for composite score leaderboards */
     fanpassLeaderboard: FanpassLeaderboardClient;
+    /** Notifications client for real-time SSE streaming */
+    notifications: NotificationsClient;
     constructor(options: ProofChainOptions);
     /**
      * Create a client for end-user JWT authentication (PWA/frontend use).
@@ -3268,4 +3447,4 @@ declare class TimeoutError extends ProofChainError {
     constructor(message?: string);
 }
 
-export { type Achievement, type ActivitySummaryView, type AddNFTRequest, type ApiKey, type AttestRequest, type AttestationMode, type AttestationResult, AuthenticationError, AuthorizationError, type AvailableView, type Badge, type BatchIngestRequest, type BatchIngestResponse, type BatchVerifyResult, type BlockchainProof, type BlockchainStats, type Certificate, type CertificateVerifyResult, CertificatesResource, type Channel, type ChannelState, type ChannelStatus, ChannelsResource, type ClaimRewardResult, type CohortDefinition, type CohortGroupStats, CohortLeaderboardClient, type CohortLeaderboardEntry, type CohortLeaderboardOptions, type CohortLeaderboardResponse, type ComprehensiveWalletInfo, type CreateAchievementRequest, type CreateApiKeyRequest, type CreateBadgeRequest, type CreateChannelRequest, type CreateDataViewRequest, type CreateDualWalletsRequest, type CreateEndUserRequest, type CreateEventRequest, type CreatePassportDefinitionRequest, type CreatePassportRequest, type CreateQuestRequest, type CreateQuestStepRequest, type CreateRewardDefinitionRequest, type CreateSchemaRequest, type CreateTemplateFieldRequest, type CreateTemplateRequest, type CreateWalletRequest as CreateUserWalletRequest, type CreateWalletRequest$1 as CreateWalletRequest, type CreateWebhookRequest, type DataViewColumn, type DataViewComputation, type DataViewDetail, type DataViewExecuteResult, type DataViewInfo, type DataViewListResponse, type DataViewPreviewRequest, type DataViewPreviewResult, type DataViewSummary, DataViewsClient, DocumentsResource, type DualWallets, type EarnedReward, type EndUser, EndUserIngestionClient, type EndUserIngestionClientOptions, type EndUserListResponse, EndUsersClient, type Event, type EventBatchProof, type EventMetadata, type EventStatus, EventsResource, type ExecuteSwapRequest, type Facet, type FacetsResponse, type FanProfileView, type FanpassGroupStats, FanpassLeaderboardClient, type FanpassLeaderboardEntry, type FanpassLeaderboardOptions, type FanpassLeaderboardResponse, type FanpassUserComparisonResponse, type FieldValue, type GDPRDeletionRequest, type GDPRDeletionResponse, type GDPRPreviewResponse, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LeaderboardUserProfile$1 as LeaderboardUserProfile, type LinkWalletRequest, type ListCertificatesRequest, type ListCohortsOptions, type ListEndUsersOptions, type ListEventsRequest, type ListQuestsOptions, type ListRewardsOptions, type ListSchemasOptions, type ManualRewardRequest, type MergeUsersRequest, type Milestone, type NFT, NetworkError, NotFoundError, type Passport, PassportClient, type PassportDefinition, type PassportFieldValue, type PassportHistory, type PassportTemplate, type PassportV2Data, type PassportWithFields, ProofChain, ProofChainError, type ProofChainOptions, type ProofVerifyResult, type Quest, type QuestStep, type QuestWithProgress, QuestsClient, RateLimitError, type RegisterWalletRequest, type RewardAsset, type RewardDefinition, type RewardEarned, RewardsClient, type Schema, type SchemaDetail, type SchemaField, type SchemaListResponse, type ValidationError$1 as SchemaValidationError, SchemasClient, type SearchFilters, type SearchQueryRequest, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type SearchStats, ServerError, type SetProfileRequest, type Settlement, type StepCompletionResult, type StepProgress, type StreamAck, type StreamEventRequest, type SwapQuote, type SwapQuoteRequest, type SwapResult, type TemplateField, type TenantInfo, TenantResource, type TierDefinition, TimeoutError, type TokenBalance, type TransferRequest, type TransferResult, type UpdateDataViewRequest, type UpdateEndUserRequest, type UpdatePassportRequest, type UpdateWebhookRequest, type UsageStats, type UserAchievement, type UserActivity, type UserActivityResponse, type UserBadge, type UserBreakdownResponse, type UserCohortBreakdownEntry, type UserQuestProgress, type UserReward$1 as UserReward, type UserRewardsResponse, type UserWalletSummary, type UserWithWallets, type UsersWithWalletsResponse, type ValidateDataRequest, ValidationError, type ValidationErrorDetail, type ValidationResult, type VaultFile, type VaultFolder, type VaultListResponse, VaultResource, type VaultStats, type VaultUploadRequest, type VerificationResult, VerifyResource, type ViewColumn, type ViewTemplate, type Wallet, type WalletBalance, WalletClient, type WalletCreationResult, type WalletStats, type Webhook, WebhooksResource };
+export { type Achievement, type ActivitySummaryView, type AddNFTRequest, type ApiKey, type AttestRequest, type AttestationMode, type AttestationResult, AuthenticationError, AuthorizationError, type AvailableView, type Badge, type BatchIngestRequest, type BatchIngestResponse, type BatchVerifyResult, type BlockchainProof, type BlockchainStats, type Certificate, type CertificateVerifyResult, CertificatesResource, type Channel, type ChannelState, type ChannelStatus, ChannelsResource, type ClaimNFTResult, type ClaimRewardResult, type CohortDefinition, type CohortGroupStats, CohortLeaderboardClient, type CohortLeaderboardEntry, type CohortLeaderboardOptions, type CohortLeaderboardResponse, type ComprehensiveWalletInfo, type CreateAchievementRequest, type CreateApiKeyRequest, type CreateBadgeRequest, type CreateChannelRequest, type CreateDataViewRequest, type CreateDualWalletsRequest, type CreateEndUserRequest, type CreateEventRequest, type CreatePassportDefinitionRequest, type CreatePassportRequest, type CreateQuestRequest, type CreateQuestStepRequest, type CreateRewardDefinitionRequest, type CreateSchemaRequest, type CreateTemplateFieldRequest, type CreateTemplateRequest, type CreateWalletRequest as CreateUserWalletRequest, type CreateWalletRequest$1 as CreateWalletRequest, type CreateWebhookRequest, type DataViewColumn, type DataViewComputation, type DataViewDetail, type DataViewExecuteResult, type DataViewInfo, type DataViewListResponse, type DataViewPreviewRequest, type DataViewPreviewResult, type DataViewSummary, DataViewsClient, type DistributeResult, DocumentsResource, type DualWallets, type EarnedReward, type EndUser, EndUserIngestionClient, type EndUserIngestionClientOptions, type EndUserListResponse, EndUsersClient, type Event, type EventBatchProof, type EventMetadata, type EventStatus, EventsResource, type ExecuteSwapRequest, type Facet, type FacetsResponse, type FanProfileView, type FanpassGroupStats, FanpassLeaderboardClient, type FanpassLeaderboardEntry, type FanpassLeaderboardOptions, type FanpassLeaderboardResponse, type FanpassUserComparisonResponse, type FieldValue, type GDPRDeletionRequest, type GDPRDeletionResponse, type GDPRPreviewResponse, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LeaderboardUserProfile$1 as LeaderboardUserProfile, type LinkWalletRequest, type ListCertificatesRequest, type ListCohortsOptions, type ListEndUsersOptions, type ListEventsRequest, type ListQuestsOptions, type ListRewardsOptions, type ListSchemasOptions, type ManualRewardRequest, type MergeUsersRequest, type Milestone, type NFT, NetworkError, NotFoundError, type NotificationCallback, type NotificationEvent, type NotificationEventType, NotificationsClient, type Passport, PassportClient, type PassportDefinition, type PassportFieldValue, type PassportHistory, type PassportTemplate, type PassportV2Data, type PassportWithFields, ProofChain, ProofChainError, type ProofChainOptions, type ProofVerifyResult, type Quest, type QuestStep, type QuestWithProgress, QuestsClient, RateLimitError, type RegisterWalletRequest, type RevokeResult, type RewardAsset, type RewardDefinition, type RewardEarned, RewardsClient, type Schema, type SchemaDetail, type SchemaField, type SchemaListResponse, type ValidationError$1 as SchemaValidationError, SchemasClient, type SearchFilters, type SearchQueryRequest, type SearchRequest, SearchResource, type SearchResponse, type SearchResult, type SearchStats, ServerError, type SetProfileRequest, type Settlement, type StepCompletionResult, type StepProgress, type StreamAck, type StreamEventRequest, type SubscribeOptions, type SwapQuote, type SwapQuoteRequest, type SwapResult, type TemplateField, type TenantInfo, TenantResource, type TierDefinition, TimeoutError, type TokenBalance, type TransferRequest, type TransferResult, type Unsubscribe, type UpdateDataViewRequest, type UpdateEndUserRequest, type UpdatePassportRequest, type UpdateWebhookRequest, type UsageStats, type UserAchievement, type UserActivity, type UserActivityResponse, type UserBadge, type UserBreakdownResponse, type UserCohortBreakdownEntry, type UserQuestProgress, type UserReward$1 as UserReward, type UserRewardsResponse, type UserWalletSummary, type UserWithWallets, type UsersWithWalletsResponse, type ValidateDataRequest, ValidationError, type ValidationErrorDetail, type ValidationResult, type VaultFile, type VaultFolder, type VaultListResponse, VaultResource, type VaultStats, type VaultUploadRequest, type VerificationResult, VerifyResource, type ViewColumn, type ViewTemplate, type Wallet, type WalletBalance, WalletClient, type WalletCreationResult, type WalletStats, type Webhook, WebhooksResource };

package/dist/index.js

@@ -34,6 +34,7 @@ __export(index_exports, {
   IngestionClient: () => IngestionClient,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
+  NotificationsClient: () => NotificationsClient,
   PassportClient: () => PassportClient,
   ProofChain: () => ProofChain,
   ProofChainError: () => ProofChainError,
@@ -1466,42 +1467,133 @@ var RewardsClient = class {
     return this.http.get(`/rewards/earned?${params.toString()}`);
   }
   /**
-   * Get earned rewards for a user (with full badge/reward details)
+   * Get earned rewards for a user (with full badge/reward details).
+   * Use this to display a user's reward collection on a dedicated screen.
+   *
+   * @example
+   * ```ts
+   * // All user rewards
+   * const all = await client.rewards.getUserRewards('user-123');
+   *
+   * // Only badges in the "Fan Pass" category
+   * const badges = await client.rewards.getUserRewards('user-123', {
+   *   reward_type: 'badge',
+   *   category: 'Fan Pass',
+   * });
+   *
+   * // Only distributed rewards
+   * const distributed = await client.rewards.getUserRewards('user-123', {
+   *   status: 'distributed',
+   * });
+   * ```
    */
   async getUserRewards(userId, options = {}) {
     const params = new URLSearchParams();
     if (options.status) params.append("status", options.status);
     if (options.reward_type) params.append("reward_type", options.reward_type);
+    if (options.category) params.append("category", options.category);
     const query = params.toString();
     return this.http.get(`/rewards/users/${userId}/rewards${query ? "?" + query : ""}`);
   }
   /**
-   * Get the public reward catalog (active, public reward definitions)
+   * Get the public reward catalog (active, public reward definitions).
    * Available to both API key and end-user JWT clients.
+   *
+   * @param category - Optional category filter (e.g. "Fan Pass", "Partner: Acme")
+   *
+   * @example
+   * ```ts
+   * // All available rewards
+   * const all = await client.rewards.getCatalog();
+   *
+   * // Only "Fan Pass" rewards
+   * const fanPass = await client.rewards.getCatalog('Fan Pass');
+   * ```
    */
-  async getCatalog() {
-    return this.http.get("/rewards/catalog");
+  async getCatalog(category) {
+    const params = new URLSearchParams();
+    if (category) params.append("category", category);
+    const query = params.toString();
+    return this.http.get(`/rewards/catalog${query ? "?" + query : ""}`);
   }
   /**
    * Claim a lazy-minted NFT reward.
    * The wallet_address receives the minted NFT. The tenant's treasury pays gas.
    * Available to both API key and end-user JWT clients (scoped to own rewards).
+   *
+   * For non-NFT rewards, use {@link distribute} instead.
    */
-  async claimReward(earnedRewardId, walletAddress) {
+  async claimNFT(earnedRewardId, walletAddress) {
     return this.http.post(`/rewards/earned/${earnedRewardId}/claim?wallet_address=${encodeURIComponent(walletAddress)}`, {});
   }
   /**
-   * Manually award rewards to users
+   * @deprecated Use {@link claimNFT} instead — this method only works for lazy-mint NFTs.
    */
-  async awardManual(request) {
+  async claimReward(earnedRewardId, walletAddress) {
+    return this.claimNFT(earnedRewardId, walletAddress);
+  }
+  /**
+   * Manually award rewards to one or more users.
+   * Works for all reward types: points, tokens, NFTs, badges, custom.
+   *
+   * @example
+   * ```ts
+   * // Award a badge to two users
+   * const rewards = await client.rewards.award({
+   *   definition_id: 'badge-def-id',
+   *   user_ids: ['user-1', 'user-2'],
+   *   distribute_immediately: true,
+   * });
+   * ```
+   */
+  async award(request) {
     return this.http.post("/rewards/award", request);
   }
   /**
-   * Distribute pending rewards (mint NFTs, transfer tokens)
+   * @deprecated Use {@link award} instead.
    */
-  async distributePending(earnedRewardId) {
+  async awardManual(request) {
+    return this.award(request);
+  }
+  /**
+   * Distribute a pending or failed reward.
+   * Works for all reward types — triggers the appropriate distribution
+   * (mint NFT, transfer tokens, issue badge, credit points, etc.).
+   *
+   * @example
+   * ```ts
+   * // Distribute a pending reward
+   * const result = await client.rewards.distribute('earned-reward-id');
+   * ```
+   */
+  async distribute(earnedRewardId) {
     return this.http.post(`/rewards/earned/${earnedRewardId}/distribute`, {});
   }
+  /**
+   * @deprecated Use {@link distribute} instead.
+   */
+  async distributePending(earnedRewardId) {
+    return this.distribute(earnedRewardId);
+  }
+  /**
+   * Distribute all pending rewards for the tenant.
+   * Queues every pending reward for background distribution.
+   */
+  async distributeAll() {
+    return this.http.post("/rewards/distribute-all-pending", {});
+  }
+  /**
+   * Revoke an earned reward.
+   *
+   * @param earnedRewardId - The earned reward ID to revoke
+   * @param reason - Reason for revocation
+   */
+  async revoke(earnedRewardId, reason) {
+    return this.http.post(
+      `/rewards/earned/${earnedRewardId}/revoke?reason=${encodeURIComponent(reason)}`,
+      {}
+    );
+  }
   // ---------------------------------------------------------------------------
   // Reward Assets
   // ---------------------------------------------------------------------------
@@ -2058,6 +2150,101 @@ var FanpassLeaderboardClient = class {
   }
 };
 
+// src/notifications.ts
+var NotificationsClient = class {
+  constructor(http) {
+    this.baseUrl = http.baseUrl || "https://api.proofchain.co.za";
+    this.authHeaders = () => {
+      const headers = {};
+      if (http.apiKey) {
+        headers["X-API-Key"] = http.apiKey;
+      }
+      if (http.userToken) {
+        headers["Authorization"] = `Bearer ${http.userToken}`;
+        if (http.tenantId) {
+          headers["X-Tenant-ID"] = http.tenantId;
+        }
+      }
+      return headers;
+    };
+  }
+  /**
+   * Subscribe to real-time notifications for a user.
+   *
+   * Opens a Server-Sent Events connection and calls the callback
+   * for each notification event (quest progress, rewards, etc.).
+   *
+   * Returns an unsubscribe function to close the connection.
+   *
+   * **Browser usage:** Works out of the box with EventSource.
+   * **Node.js usage:** Requires the `eventsource` package.
+   *
+   * @param userId - The external user ID to subscribe for
+   * @param callback - Function called for each notification event
+   * @param options - Connection options (reconnect, callbacks)
+   * @returns Unsubscribe function to close the connection
+   */
+  subscribe(userId, callback, options = {}) {
+    const {
+      onConnect,
+      onDisconnect,
+      onError,
+      autoReconnect = true,
+      reconnectDelay = 3e3
+    } = options;
+    let eventSource = null;
+    let closed = false;
+    let reconnectTimer = null;
+    const connect = () => {
+      if (closed) return;
+      const headers = this.authHeaders();
+      const params = new URLSearchParams({ user_id: userId });
+      if (headers["X-API-Key"]) {
+        params.append("api_key", headers["X-API-Key"]);
+      }
+      if (headers["Authorization"]) {
+        params.append("token", headers["Authorization"].replace("Bearer ", ""));
+      }
+      if (headers["X-Tenant-ID"]) {
+        params.append("tenant_id", headers["X-Tenant-ID"]);
+      }
+      const url = `${this.baseUrl}/notifications/stream?${params.toString()}`;
+      const ES = typeof EventSource !== "undefined" ? EventSource : (() => {
+        throw new Error('EventSource not available. Install the "eventsource" package for Node.js.');
+      })();
+      eventSource = new ES(url);
+      eventSource.onmessage = (e) => {
+        try {
+          const event = JSON.parse(e.data);
+          if (event.event === "connected") {
+            onConnect?.();
+          } else {
+            callback(event);
+          }
+        } catch (err) {
+          onError?.(new Error(`Failed to parse notification: ${e.data}`));
+        }
+      };
+      eventSource.onerror = () => {
+        if (closed) return;
+        onDisconnect?.();
+        if (eventSource?.readyState === 2 && autoReconnect) {
+          reconnectTimer = setTimeout(connect, reconnectDelay);
+        }
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (eventSource) {
+        eventSource.close();
+        eventSource = null;
+      }
+    };
+  }
+};
+
 // src/client.ts
 var DocumentsResource = class {
   constructor(http) {
@@ -2355,6 +2542,7 @@ var ProofChain = class _ProofChain {
     this.dataViews = new DataViewsClient(this.http);
     this.cohorts = new CohortLeaderboardClient(this.http);
     this.fanpassLeaderboard = new FanpassLeaderboardClient(this.http);
+    this.notifications = new NotificationsClient(this.http);
   }
   /**
    * Create a client for end-user JWT authentication (PWA/frontend use).
@@ -2698,6 +2886,7 @@ var EndUserIngestionClient = class {
   IngestionClient,
   NetworkError,
   NotFoundError,
+  NotificationsClient,
   PassportClient,
   ProofChain,
   ProofChainError,

package/dist/index.mjs

@@ -1411,42 +1411,133 @@ var RewardsClient = class {
     return this.http.get(`/rewards/earned?${params.toString()}`);
   }
   /**
-   * Get earned rewards for a user (with full badge/reward details)
+   * Get earned rewards for a user (with full badge/reward details).
+   * Use this to display a user's reward collection on a dedicated screen.
+   *
+   * @example
+   * ```ts
+   * // All user rewards
+   * const all = await client.rewards.getUserRewards('user-123');
+   *
+   * // Only badges in the "Fan Pass" category
+   * const badges = await client.rewards.getUserRewards('user-123', {
+   *   reward_type: 'badge',
+   *   category: 'Fan Pass',
+   * });
+   *
+   * // Only distributed rewards
+   * const distributed = await client.rewards.getUserRewards('user-123', {
+   *   status: 'distributed',
+   * });
+   * ```
    */
   async getUserRewards(userId, options = {}) {
     const params = new URLSearchParams();
     if (options.status) params.append("status", options.status);
     if (options.reward_type) params.append("reward_type", options.reward_type);
+    if (options.category) params.append("category", options.category);
     const query = params.toString();
     return this.http.get(`/rewards/users/${userId}/rewards${query ? "?" + query : ""}`);
   }
   /**
-   * Get the public reward catalog (active, public reward definitions)
+   * Get the public reward catalog (active, public reward definitions).
    * Available to both API key and end-user JWT clients.
+   *
+   * @param category - Optional category filter (e.g. "Fan Pass", "Partner: Acme")
+   *
+   * @example
+   * ```ts
+   * // All available rewards
+   * const all = await client.rewards.getCatalog();
+   *
+   * // Only "Fan Pass" rewards
+   * const fanPass = await client.rewards.getCatalog('Fan Pass');
+   * ```
    */
-  async getCatalog() {
-    return this.http.get("/rewards/catalog");
+  async getCatalog(category) {
+    const params = new URLSearchParams();
+    if (category) params.append("category", category);
+    const query = params.toString();
+    return this.http.get(`/rewards/catalog${query ? "?" + query : ""}`);
   }
   /**
    * Claim a lazy-minted NFT reward.
    * The wallet_address receives the minted NFT. The tenant's treasury pays gas.
    * Available to both API key and end-user JWT clients (scoped to own rewards).
+   *
+   * For non-NFT rewards, use {@link distribute} instead.
    */
-  async claimReward(earnedRewardId, walletAddress) {
+  async claimNFT(earnedRewardId, walletAddress) {
     return this.http.post(`/rewards/earned/${earnedRewardId}/claim?wallet_address=${encodeURIComponent(walletAddress)}`, {});
   }
   /**
-   * Manually award rewards to users
+   * @deprecated Use {@link claimNFT} instead — this method only works for lazy-mint NFTs.
    */
-  async awardManual(request) {
+  async claimReward(earnedRewardId, walletAddress) {
+    return this.claimNFT(earnedRewardId, walletAddress);
+  }
+  /**
+   * Manually award rewards to one or more users.
+   * Works for all reward types: points, tokens, NFTs, badges, custom.
+   *
+   * @example
+   * ```ts
+   * // Award a badge to two users
+   * const rewards = await client.rewards.award({
+   *   definition_id: 'badge-def-id',
+   *   user_ids: ['user-1', 'user-2'],
+   *   distribute_immediately: true,
+   * });
+   * ```
+   */
+  async award(request) {
     return this.http.post("/rewards/award", request);
   }
   /**
-   * Distribute pending rewards (mint NFTs, transfer tokens)
+   * @deprecated Use {@link award} instead.
    */
-  async distributePending(earnedRewardId) {
+  async awardManual(request) {
+    return this.award(request);
+  }
+  /**
+   * Distribute a pending or failed reward.
+   * Works for all reward types — triggers the appropriate distribution
+   * (mint NFT, transfer tokens, issue badge, credit points, etc.).
+   *
+   * @example
+   * ```ts
+   * // Distribute a pending reward
+   * const result = await client.rewards.distribute('earned-reward-id');
+   * ```
+   */
+  async distribute(earnedRewardId) {
     return this.http.post(`/rewards/earned/${earnedRewardId}/distribute`, {});
   }
+  /**
+   * @deprecated Use {@link distribute} instead.
+   */
+  async distributePending(earnedRewardId) {
+    return this.distribute(earnedRewardId);
+  }
+  /**
+   * Distribute all pending rewards for the tenant.
+   * Queues every pending reward for background distribution.
+   */
+  async distributeAll() {
+    return this.http.post("/rewards/distribute-all-pending", {});
+  }
+  /**
+   * Revoke an earned reward.
+   *
+   * @param earnedRewardId - The earned reward ID to revoke
+   * @param reason - Reason for revocation
+   */
+  async revoke(earnedRewardId, reason) {
+    return this.http.post(
+      `/rewards/earned/${earnedRewardId}/revoke?reason=${encodeURIComponent(reason)}`,
+      {}
+    );
+  }
   // ---------------------------------------------------------------------------
   // Reward Assets
   // ---------------------------------------------------------------------------
@@ -2003,6 +2094,101 @@ var FanpassLeaderboardClient = class {
   }
 };
 
+// src/notifications.ts
+var NotificationsClient = class {
+  constructor(http) {
+    this.baseUrl = http.baseUrl || "https://api.proofchain.co.za";
+    this.authHeaders = () => {
+      const headers = {};
+      if (http.apiKey) {
+        headers["X-API-Key"] = http.apiKey;
+      }
+      if (http.userToken) {
+        headers["Authorization"] = `Bearer ${http.userToken}`;
+        if (http.tenantId) {
+          headers["X-Tenant-ID"] = http.tenantId;
+        }
+      }
+      return headers;
+    };
+  }
+  /**
+   * Subscribe to real-time notifications for a user.
+   *
+   * Opens a Server-Sent Events connection and calls the callback
+   * for each notification event (quest progress, rewards, etc.).
+   *
+   * Returns an unsubscribe function to close the connection.
+   *
+   * **Browser usage:** Works out of the box with EventSource.
+   * **Node.js usage:** Requires the `eventsource` package.
+   *
+   * @param userId - The external user ID to subscribe for
+   * @param callback - Function called for each notification event
+   * @param options - Connection options (reconnect, callbacks)
+   * @returns Unsubscribe function to close the connection
+   */
+  subscribe(userId, callback, options = {}) {
+    const {
+      onConnect,
+      onDisconnect,
+      onError,
+      autoReconnect = true,
+      reconnectDelay = 3e3
+    } = options;
+    let eventSource = null;
+    let closed = false;
+    let reconnectTimer = null;
+    const connect = () => {
+      if (closed) return;
+      const headers = this.authHeaders();
+      const params = new URLSearchParams({ user_id: userId });
+      if (headers["X-API-Key"]) {
+        params.append("api_key", headers["X-API-Key"]);
+      }
+      if (headers["Authorization"]) {
+        params.append("token", headers["Authorization"].replace("Bearer ", ""));
+      }
+      if (headers["X-Tenant-ID"]) {
+        params.append("tenant_id", headers["X-Tenant-ID"]);
+      }
+      const url = `${this.baseUrl}/notifications/stream?${params.toString()}`;
+      const ES = typeof EventSource !== "undefined" ? EventSource : (() => {
+        throw new Error('EventSource not available. Install the "eventsource" package for Node.js.');
+      })();
+      eventSource = new ES(url);
+      eventSource.onmessage = (e) => {
+        try {
+          const event = JSON.parse(e.data);
+          if (event.event === "connected") {
+            onConnect?.();
+          } else {
+            callback(event);
+          }
+        } catch (err) {
+          onError?.(new Error(`Failed to parse notification: ${e.data}`));
+        }
+      };
+      eventSource.onerror = () => {
+        if (closed) return;
+        onDisconnect?.();
+        if (eventSource?.readyState === 2 && autoReconnect) {
+          reconnectTimer = setTimeout(connect, reconnectDelay);
+        }
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (eventSource) {
+        eventSource.close();
+        eventSource = null;
+      }
+    };
+  }
+};
+
 // src/client.ts
 var DocumentsResource = class {
   constructor(http) {
@@ -2300,6 +2486,7 @@ var ProofChain = class _ProofChain {
     this.dataViews = new DataViewsClient(this.http);
     this.cohorts = new CohortLeaderboardClient(this.http);
     this.fanpassLeaderboard = new FanpassLeaderboardClient(this.http);
+    this.notifications = new NotificationsClient(this.http);
   }
   /**
    * Create a client for end-user JWT authentication (PWA/frontend use).
@@ -2642,6 +2829,7 @@ export {
   IngestionClient,
   NetworkError,
   NotFoundError,
+  NotificationsClient,
   PassportClient,
   ProofChain,
   ProofChainError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofchain/sdk",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Official JavaScript/TypeScript SDK for ProofChain - blockchain-anchored document attestation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",