@proofchain/sdk 2.15.0 → 2.16.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 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[]>;
     /**
-     * Manually award rewards to users
+     * @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)
      */
@@ -3268,4 +3357,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 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 };

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 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[]>;
     /**
-     * Manually award rewards to users
+     * @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)
      */
@@ -3268,4 +3357,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 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 };

package/dist/index.js

@@ -1466,42 +1466,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
   // ---------------------------------------------------------------------------

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
   // ---------------------------------------------------------------------------

package/package.json

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