@proofchain/sdk 2.14.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 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)
      */
@@ -3128,6 +3217,16 @@ interface IngestionClientOptions {
     ingestUrl?: string;
     timeout?: number;
 }
+interface EndUserIngestionClientOptions {
+    /** End-user JWT from your auth provider (Auth0, Firebase, Clerk, etc.) */
+    userToken: string;
+    /** Proofchain tenant slug or client_id */
+    tenantId: string;
+    /** Base URL for the tenant API (default: https://api.proofchain.co.za) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
 /**
  * High-performance ingestion client for the Rust ingestion API.
  *
@@ -3176,6 +3275,47 @@ declare class IngestionClient {
         ipfsHash?: string;
     }>;
 }
+/**
+ * End-user ingestion client that routes events through the tenant-api JWKS proxy.
+ * Events are validated (JWT + user_id enforcement) then forwarded to the Rust
+ * ingestion pipeline for consistent processing.
+ *
+ * @example
+ * ```typescript
+ * const ingestion = new EndUserIngestionClient({
+ *   userToken: auth.getIdToken(),
+ *   tenantId: 'my-tenant-slug',
+ * });
+ *
+ * // Submit event (user_id MUST match the JWT's user identity)
+ * const result = await ingestion.ingest({
+ *   userId: 'user-123',
+ *   eventType: 'page_view',
+ *   data: { page: '/home' },
+ * });
+ * ```
+ */
+declare class EndUserIngestionClient {
+    private userToken;
+    private tenantId;
+    private apiUrl;
+    private timeout;
+    constructor(options: EndUserIngestionClientOptions);
+    /** Update the end-user JWT token (e.g., after token refresh). */
+    setToken(userToken: string): void;
+    private getHeaders;
+    private handleResponse;
+    /**
+     * Submit a single event as an authenticated end-user.
+     * The userId MUST match the JWT's user identity or the request will be rejected with 403.
+     */
+    ingest(request: IngestEventRequest): Promise<IngestEventResponse>;
+    /**
+     * Submit a batch of events as an authenticated end-user (up to 100 events).
+     * ALL events must have userId matching the JWT's user identity.
+     */
+    ingestBatch(request: BatchIngestRequest): Promise<BatchIngestResponse>;
+}
 
 /**
  * ProofChain SDK Error Classes
@@ -3217,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, 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 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)
      */
@@ -3128,6 +3217,16 @@ interface IngestionClientOptions {
     ingestUrl?: string;
     timeout?: number;
 }
+interface EndUserIngestionClientOptions {
+    /** End-user JWT from your auth provider (Auth0, Firebase, Clerk, etc.) */
+    userToken: string;
+    /** Proofchain tenant slug or client_id */
+    tenantId: string;
+    /** Base URL for the tenant API (default: https://api.proofchain.co.za) */
+    apiUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
 /**
  * High-performance ingestion client for the Rust ingestion API.
  *
@@ -3176,6 +3275,47 @@ declare class IngestionClient {
         ipfsHash?: string;
     }>;
 }
+/**
+ * End-user ingestion client that routes events through the tenant-api JWKS proxy.
+ * Events are validated (JWT + user_id enforcement) then forwarded to the Rust
+ * ingestion pipeline for consistent processing.
+ *
+ * @example
+ * ```typescript
+ * const ingestion = new EndUserIngestionClient({
+ *   userToken: auth.getIdToken(),
+ *   tenantId: 'my-tenant-slug',
+ * });
+ *
+ * // Submit event (user_id MUST match the JWT's user identity)
+ * const result = await ingestion.ingest({
+ *   userId: 'user-123',
+ *   eventType: 'page_view',
+ *   data: { page: '/home' },
+ * });
+ * ```
+ */
+declare class EndUserIngestionClient {
+    private userToken;
+    private tenantId;
+    private apiUrl;
+    private timeout;
+    constructor(options: EndUserIngestionClientOptions);
+    /** Update the end-user JWT token (e.g., after token refresh). */
+    setToken(userToken: string): void;
+    private getHeaders;
+    private handleResponse;
+    /**
+     * Submit a single event as an authenticated end-user.
+     * The userId MUST match the JWT's user identity or the request will be rejected with 403.
+     */
+    ingest(request: IngestEventRequest): Promise<IngestEventResponse>;
+    /**
+     * Submit a batch of events as an authenticated end-user (up to 100 events).
+     * ALL events must have userId matching the JWT's user identity.
+     */
+    ingestBatch(request: BatchIngestRequest): Promise<BatchIngestResponse>;
+}
 
 /**
  * ProofChain SDK Error Classes
@@ -3217,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, 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

@@ -27,6 +27,7 @@ __export(index_exports, {
   CohortLeaderboardClient: () => CohortLeaderboardClient,
   DataViewsClient: () => DataViewsClient,
   DocumentsResource: () => DocumentsResource,
+  EndUserIngestionClient: () => EndUserIngestionClient,
   EndUsersClient: () => EndUsersClient,
   EventsResource: () => EventsResource,
   FanpassLeaderboardClient: () => FanpassLeaderboardClient,
@@ -1465,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
   // ---------------------------------------------------------------------------
@@ -2552,6 +2644,135 @@ var IngestionClient = class {
     }
   }
 };
+var EndUserIngestionClient = class {
+  constructor(options) {
+    this.userToken = options.userToken;
+    this.tenantId = options.tenantId;
+    this.apiUrl = (options.apiUrl || "https://api.proofchain.co.za").replace(/\/$/, "");
+    this.timeout = options.timeout || 3e4;
+  }
+  /** Update the end-user JWT token (e.g., after token refresh). */
+  setToken(userToken) {
+    this.userToken = userToken;
+  }
+  getHeaders() {
+    return {
+      "Authorization": `Bearer ${this.userToken}`,
+      "X-Tenant-ID": this.tenantId,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT2
+    };
+  }
+  async handleResponse(response) {
+    const contentType = response.headers.get("content-type");
+    const isJson = contentType?.includes("application/json");
+    if (response.ok) {
+      if (response.status === 204 || !isJson) {
+        return {};
+      }
+      return response.json();
+    }
+    const body = isJson ? await response.json().catch(() => ({})) : {};
+    const message = body.detail || body.message || `HTTP ${response.status}`;
+    switch (response.status) {
+      case 401:
+        throw new AuthenticationError(message);
+      case 403:
+        throw new ProofChainError(message, 403, body);
+      case 422:
+      case 400:
+        throw new ValidationError(message, body.errors);
+      case 429:
+        const retryAfter = response.headers.get("Retry-After");
+        throw new RateLimitError(retryAfter ? parseInt(retryAfter, 10) : void 0);
+      default:
+        if (response.status >= 500) {
+          throw new ServerError(message, response.status);
+        }
+        throw new ProofChainError(message, response.status, body);
+    }
+  }
+  /**
+   * Submit a single event as an authenticated end-user.
+   * The userId MUST match the JWT's user identity or the request will be rejected with 403.
+   */
+  async ingest(request) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/end-user/events/ingest`, {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          user_id: request.userId,
+          event_type: request.eventType,
+          data: request.data || {},
+          event_source: request.eventSource || "end_user_sdk"
+        }),
+        signal: controller.signal
+      });
+      const result = await this.handleResponse(response);
+      return {
+        eventId: result.event_id,
+        certificateId: result.certificate_id,
+        status: result.status,
+        queuePosition: result.queue_position,
+        estimatedConfirmation: result.estimated_confirmation
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Submit a batch of events as an authenticated end-user (up to 100 events).
+   * ALL events must have userId matching the JWT's user identity.
+   */
+  async ingestBatch(request) {
+    if (request.events.length > 100) {
+      throw new ValidationError("End-user batch size cannot exceed 100 events");
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 2);
+    try {
+      const response = await fetch(`${this.apiUrl}/end-user/events/ingest/batch`, {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          events: request.events.map((e) => ({
+            user_id: e.userId,
+            event_type: e.eventType,
+            data: e.data || {},
+            event_source: e.eventSource || "end_user_sdk"
+          }))
+        }),
+        signal: controller.signal
+      });
+      const result = await this.handleResponse(response);
+      return {
+        totalEvents: result.total_events || result.total,
+        queued: result.queued,
+        failed: result.failed,
+        results: (result.results || result.responses || []).map((r) => ({
+          eventId: r.event_id,
+          certificateId: r.certificate_id,
+          status: r.status
+        }))
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
@@ -2561,6 +2782,7 @@ var IngestionClient = class {
   CohortLeaderboardClient,
   DataViewsClient,
   DocumentsResource,
+  EndUserIngestionClient,
   EndUsersClient,
   EventsResource,
   FanpassLeaderboardClient,

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
   // ---------------------------------------------------------------------------
@@ -2498,6 +2589,135 @@ var IngestionClient = class {
     }
   }
 };
+var EndUserIngestionClient = class {
+  constructor(options) {
+    this.userToken = options.userToken;
+    this.tenantId = options.tenantId;
+    this.apiUrl = (options.apiUrl || "https://api.proofchain.co.za").replace(/\/$/, "");
+    this.timeout = options.timeout || 3e4;
+  }
+  /** Update the end-user JWT token (e.g., after token refresh). */
+  setToken(userToken) {
+    this.userToken = userToken;
+  }
+  getHeaders() {
+    return {
+      "Authorization": `Bearer ${this.userToken}`,
+      "X-Tenant-ID": this.tenantId,
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT2
+    };
+  }
+  async handleResponse(response) {
+    const contentType = response.headers.get("content-type");
+    const isJson = contentType?.includes("application/json");
+    if (response.ok) {
+      if (response.status === 204 || !isJson) {
+        return {};
+      }
+      return response.json();
+    }
+    const body = isJson ? await response.json().catch(() => ({})) : {};
+    const message = body.detail || body.message || `HTTP ${response.status}`;
+    switch (response.status) {
+      case 401:
+        throw new AuthenticationError(message);
+      case 403:
+        throw new ProofChainError(message, 403, body);
+      case 422:
+      case 400:
+        throw new ValidationError(message, body.errors);
+      case 429:
+        const retryAfter = response.headers.get("Retry-After");
+        throw new RateLimitError(retryAfter ? parseInt(retryAfter, 10) : void 0);
+      default:
+        if (response.status >= 500) {
+          throw new ServerError(message, response.status);
+        }
+        throw new ProofChainError(message, response.status, body);
+    }
+  }
+  /**
+   * Submit a single event as an authenticated end-user.
+   * The userId MUST match the JWT's user identity or the request will be rejected with 403.
+   */
+  async ingest(request) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.apiUrl}/end-user/events/ingest`, {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          user_id: request.userId,
+          event_type: request.eventType,
+          data: request.data || {},
+          event_source: request.eventSource || "end_user_sdk"
+        }),
+        signal: controller.signal
+      });
+      const result = await this.handleResponse(response);
+      return {
+        eventId: result.event_id,
+        certificateId: result.certificate_id,
+        status: result.status,
+        queuePosition: result.queue_position,
+        estimatedConfirmation: result.estimated_confirmation
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Submit a batch of events as an authenticated end-user (up to 100 events).
+   * ALL events must have userId matching the JWT's user identity.
+   */
+  async ingestBatch(request) {
+    if (request.events.length > 100) {
+      throw new ValidationError("End-user batch size cannot exceed 100 events");
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 2);
+    try {
+      const response = await fetch(`${this.apiUrl}/end-user/events/ingest/batch`, {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: JSON.stringify({
+          events: request.events.map((e) => ({
+            user_id: e.userId,
+            event_type: e.eventType,
+            data: e.data || {},
+            event_source: e.eventSource || "end_user_sdk"
+          }))
+        }),
+        signal: controller.signal
+      });
+      const result = await this.handleResponse(response);
+      return {
+        totalEvents: result.total_events || result.total,
+        queued: result.queued,
+        failed: result.failed,
+        results: (result.results || result.responses || []).map((r) => ({
+          eventId: r.event_id,
+          certificateId: r.certificate_id,
+          status: r.status
+        }))
+      };
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
 export {
   AuthenticationError,
   AuthorizationError,
@@ -2506,6 +2726,7 @@ export {
   CohortLeaderboardClient,
   DataViewsClient,
   DocumentsResource,
+  EndUserIngestionClient,
   EndUsersClient,
   EventsResource,
   FanpassLeaderboardClient,

package/package.json

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