@proofchain/sdk 2.16.0 → 2.17.0

package/dist/index.d.mts

@@ -2948,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
  */
@@ -3142,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).
@@ -3357,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 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 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 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

@@ -2948,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
  */
@@ -3142,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).
@@ -3357,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 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 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 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,
@@ -2149,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) {
@@ -2446,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).
@@ -2789,6 +2886,7 @@ var EndUserIngestionClient = class {
   IngestionClient,
   NetworkError,
   NotFoundError,
+  NotificationsClient,
   PassportClient,
   ProofChain,
   ProofChainError,

package/dist/index.mjs

@@ -2094,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) {
@@ -2391,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).
@@ -2733,6 +2829,7 @@ export {
   IngestionClient,
   NetworkError,
   NotFoundError,
+  NotificationsClient,
   PassportClient,
   ProofChain,
   ProofChainError,

package/package.json

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