@proofchain/sdk 2.4.0 → 2.5.0

package/README.md

@@ -196,6 +196,50 @@ const webhooks = await client.webhooks.list();
 await client.webhooks.delete(webhook.id);
 ```
 
+### Quests
+
+Quests are gamified user journeys with steps that can be completed via events.
+
+```typescript
+// List available quests for a user (with their progress)
+const quests = await client.quests.listAvailable(userId);
+// Returns: { quest: Quest, progress?: UserQuestProgress }[]
+
+// Each quest has a type that determines behavior:
+// - 'epic': Long-form quests - user must explicitly start
+// - 'quick_hit': Short quests - auto-enrolls on matching event
+// - 'challenge': Time-limited quests - auto-enrolls on matching event
+
+for (const { quest, progress } of quests) {
+  console.log(`${quest.name} (${quest.quest_type})`);
+  if (progress) {
+    console.log(`  Progress: ${progress.completion_percentage}%`);
+  }
+}
+
+// Start an Epic quest (required for epic type only)
+const progress = await client.quests.startQuest(questId, userId);
+
+// Get user's progress on a specific quest
+const questProgress = await client.quests.getUserProgress(questId, userId);
+
+// Get all quest progress for a user
+const allProgress = await client.quests.getAllUserProgress(userId);
+
+// Complete a step manually (for manual step types)
+const result = await client.quests.completeStep(questId, userId, stepIndex);
+console.log('Step completed:', result.step_completed);
+console.log('Quest completed:', result.quest_completed);
+```
+
+**Quest Types:**
+
+| Type | Behavior |
+|------|----------|
+| `epic` | Long-form, multi-step quests. User must call `startQuest()` to begin. |
+| `quick_hit` | Short, easy quests. Auto-enrolls when user triggers a matching event. |
+| `challenge` | Time-limited or competitive. Auto-enrolls when user triggers a matching event. |
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -2455,6 +2455,157 @@ declare class DataViewsClient {
     getTemplates(): Promise<ViewTemplate[]>;
 }
 
+/**
+ * Cohort Leaderboard API Client
+ *
+ * Manage cohort definitions, scoring, and filtered leaderboards with percentiles.
+ */
+
+interface CohortLeaderboardEntry {
+    rank: number;
+    user_id: string;
+    score: number;
+    percentile_global: number;
+    percentile_filtered: number | null;
+    computed_at?: string;
+}
+interface CohortGroupStats {
+    filtered_avg_percentile: number | null;
+    filtered_top_n_avg_percentile: number | null;
+    global_count: number;
+    global_avg_percentile: number;
+}
+interface CohortLeaderboardResponse {
+    cohort_id: string;
+    cohort_name: string;
+    filter: Record<string, unknown>;
+    total_users: number;
+    group_stats: CohortGroupStats;
+    leaderboard: CohortLeaderboardEntry[];
+}
+interface CohortDefinition {
+    id: string;
+    tenant_id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    scoring_type: string;
+    icon?: string;
+    color?: string;
+    status: 'active' | 'inactive' | 'draft';
+    avg_score?: number;
+    total_users?: number;
+    created_at: string;
+    updated_at: string;
+}
+interface UserCohortBreakdownEntry {
+    cohort_id: string;
+    cohort_slug: string;
+    cohort_name: string;
+    icon?: string;
+    color?: string;
+    user_percentile: number;
+    filtered_group_avg_percentile: number | null;
+    global_group_avg_percentile: number;
+}
+interface UserBreakdownResponse {
+    user_id: string;
+    filter: Record<string, unknown>;
+    cohorts: UserCohortBreakdownEntry[];
+}
+interface CohortLeaderboardOptions {
+    filters?: Record<string, string>;
+    country?: string;
+    limit?: number;
+    top_n?: number;
+    fresh?: boolean;
+}
+interface ListCohortsOptions {
+    status?: 'active' | 'inactive' | 'draft';
+    limit?: number;
+    offset?: number;
+}
+declare class CohortLeaderboardClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all cohort definitions
+     */
+    list(options?: ListCohortsOptions): Promise<CohortDefinition[]>;
+    /**
+     * Get a cohort definition by ID
+     */
+    get(cohortId: string): Promise<CohortDefinition>;
+    /**
+     * Get filtered cohort leaderboard with both global and filtered percentiles
+     */
+    getLeaderboard(cohortId: string, options?: CohortLeaderboardOptions): Promise<CohortLeaderboardResponse>;
+    /**
+     * Get user's breakdown across all cohorts for spider charts
+     */
+    getUserBreakdown(userId: string, options?: {
+        filters?: Record<string, string>;
+        country?: string;
+    }): Promise<UserBreakdownResponse>;
+}
+
+/**
+ * Fanpass Leaderboard API Client
+ *
+ * Manage fanpass composite scores and filtered leaderboards.
+ */
+
+interface FanpassLeaderboardEntry {
+    rank: number;
+    user_id: string;
+    fan_score: number;
+    raw_score: number;
+    percentile: number;
+    computed_at?: string;
+}
+interface FanpassGroupStats {
+    avg_fan_score: number;
+    top_n_avg_fan_score: number;
+    global_count: number;
+    global_avg_fan_score: number;
+}
+interface FanpassLeaderboardResponse {
+    aggregation_rule_id: string | null;
+    aggregation_rule_name: string | null;
+    filter: Record<string, unknown>;
+    total_users: number;
+    group_stats: FanpassGroupStats;
+    leaderboard: FanpassLeaderboardEntry[];
+}
+interface FanpassUserComparisonResponse {
+    user_id: string;
+    filter: Record<string, unknown>;
+    cohorts: UserCohortBreakdownEntry[];
+}
+interface FanpassLeaderboardOptions {
+    aggregationRuleId?: string;
+    filters?: Record<string, string>;
+    country?: string;
+    limit?: number;
+    top_n?: number;
+    fresh?: boolean;
+}
+declare class FanpassLeaderboardClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get fanpass leaderboard with composite scores
+     */
+    getLeaderboard(options?: FanpassLeaderboardOptions): Promise<FanpassLeaderboardResponse>;
+    /**
+     * Get user's comparison across all cohorts (spider chart data)
+     */
+    getUserComparison(userId: string, options?: {
+        filters?: Record<string, string>;
+        country?: string;
+    }): Promise<FanpassUserComparisonResponse>;
+}
+
 /**
  * ProofChain Client
  */
@@ -2645,6 +2796,10 @@ declare class ProofChain {
     schemas: SchemasClient;
     /** Data Views client for custom data view operations */
     dataViews: DataViewsClient;
+    /** Cohort leaderboard client for filtered leaderboards and percentiles */
+    cohorts: CohortLeaderboardClient;
+    /** Fanpass leaderboard client for composite score leaderboards */
+    fanpassLeaderboard: FanpassLeaderboardClient;
     constructor(options: ProofChainOptions);
     /**
      * Create a client from environment variables.
@@ -2788,4 +2943,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 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, 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 FieldValue, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LinkWalletRequest, type ListCertificatesRequest, 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 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 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 UserQuestProgress, 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 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 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, 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 IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, 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 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 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 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 WalletStats, type Webhook, WebhooksResource };

package/dist/index.d.ts

@@ -2455,6 +2455,157 @@ declare class DataViewsClient {
     getTemplates(): Promise<ViewTemplate[]>;
 }
 
+/**
+ * Cohort Leaderboard API Client
+ *
+ * Manage cohort definitions, scoring, and filtered leaderboards with percentiles.
+ */
+
+interface CohortLeaderboardEntry {
+    rank: number;
+    user_id: string;
+    score: number;
+    percentile_global: number;
+    percentile_filtered: number | null;
+    computed_at?: string;
+}
+interface CohortGroupStats {
+    filtered_avg_percentile: number | null;
+    filtered_top_n_avg_percentile: number | null;
+    global_count: number;
+    global_avg_percentile: number;
+}
+interface CohortLeaderboardResponse {
+    cohort_id: string;
+    cohort_name: string;
+    filter: Record<string, unknown>;
+    total_users: number;
+    group_stats: CohortGroupStats;
+    leaderboard: CohortLeaderboardEntry[];
+}
+interface CohortDefinition {
+    id: string;
+    tenant_id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    scoring_type: string;
+    icon?: string;
+    color?: string;
+    status: 'active' | 'inactive' | 'draft';
+    avg_score?: number;
+    total_users?: number;
+    created_at: string;
+    updated_at: string;
+}
+interface UserCohortBreakdownEntry {
+    cohort_id: string;
+    cohort_slug: string;
+    cohort_name: string;
+    icon?: string;
+    color?: string;
+    user_percentile: number;
+    filtered_group_avg_percentile: number | null;
+    global_group_avg_percentile: number;
+}
+interface UserBreakdownResponse {
+    user_id: string;
+    filter: Record<string, unknown>;
+    cohorts: UserCohortBreakdownEntry[];
+}
+interface CohortLeaderboardOptions {
+    filters?: Record<string, string>;
+    country?: string;
+    limit?: number;
+    top_n?: number;
+    fresh?: boolean;
+}
+interface ListCohortsOptions {
+    status?: 'active' | 'inactive' | 'draft';
+    limit?: number;
+    offset?: number;
+}
+declare class CohortLeaderboardClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all cohort definitions
+     */
+    list(options?: ListCohortsOptions): Promise<CohortDefinition[]>;
+    /**
+     * Get a cohort definition by ID
+     */
+    get(cohortId: string): Promise<CohortDefinition>;
+    /**
+     * Get filtered cohort leaderboard with both global and filtered percentiles
+     */
+    getLeaderboard(cohortId: string, options?: CohortLeaderboardOptions): Promise<CohortLeaderboardResponse>;
+    /**
+     * Get user's breakdown across all cohorts for spider charts
+     */
+    getUserBreakdown(userId: string, options?: {
+        filters?: Record<string, string>;
+        country?: string;
+    }): Promise<UserBreakdownResponse>;
+}
+
+/**
+ * Fanpass Leaderboard API Client
+ *
+ * Manage fanpass composite scores and filtered leaderboards.
+ */
+
+interface FanpassLeaderboardEntry {
+    rank: number;
+    user_id: string;
+    fan_score: number;
+    raw_score: number;
+    percentile: number;
+    computed_at?: string;
+}
+interface FanpassGroupStats {
+    avg_fan_score: number;
+    top_n_avg_fan_score: number;
+    global_count: number;
+    global_avg_fan_score: number;
+}
+interface FanpassLeaderboardResponse {
+    aggregation_rule_id: string | null;
+    aggregation_rule_name: string | null;
+    filter: Record<string, unknown>;
+    total_users: number;
+    group_stats: FanpassGroupStats;
+    leaderboard: FanpassLeaderboardEntry[];
+}
+interface FanpassUserComparisonResponse {
+    user_id: string;
+    filter: Record<string, unknown>;
+    cohorts: UserCohortBreakdownEntry[];
+}
+interface FanpassLeaderboardOptions {
+    aggregationRuleId?: string;
+    filters?: Record<string, string>;
+    country?: string;
+    limit?: number;
+    top_n?: number;
+    fresh?: boolean;
+}
+declare class FanpassLeaderboardClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get fanpass leaderboard with composite scores
+     */
+    getLeaderboard(options?: FanpassLeaderboardOptions): Promise<FanpassLeaderboardResponse>;
+    /**
+     * Get user's comparison across all cohorts (spider chart data)
+     */
+    getUserComparison(userId: string, options?: {
+        filters?: Record<string, string>;
+        country?: string;
+    }): Promise<FanpassUserComparisonResponse>;
+}
+
 /**
  * ProofChain Client
  */
@@ -2645,6 +2796,10 @@ declare class ProofChain {
     schemas: SchemasClient;
     /** Data Views client for custom data view operations */
     dataViews: DataViewsClient;
+    /** Cohort leaderboard client for filtered leaderboards and percentiles */
+    cohorts: CohortLeaderboardClient;
+    /** Fanpass leaderboard client for composite score leaderboards */
+    fanpassLeaderboard: FanpassLeaderboardClient;
     constructor(options: ProofChainOptions);
     /**
      * Create a client from environment variables.
@@ -2788,4 +2943,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 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, 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 FieldValue, type IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, type LinkWalletRequest, type ListCertificatesRequest, 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 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 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 UserQuestProgress, 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 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 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, 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 IngestEventRequest, type IngestEventResponse, IngestionClient, type IngestionClientOptions, type IssueCertificateRequest, 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 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 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 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 WalletStats, type Webhook, WebhooksResource };

package/dist/index.js

@@ -24,10 +24,12 @@ __export(index_exports, {
   AuthorizationError: () => AuthorizationError,
   CertificatesResource: () => CertificatesResource,
   ChannelsResource: () => ChannelsResource,
+  CohortLeaderboardClient: () => CohortLeaderboardClient,
   DataViewsClient: () => DataViewsClient,
   DocumentsResource: () => DocumentsResource,
   EndUsersClient: () => EndUsersClient,
   EventsResource: () => EventsResource,
+  FanpassLeaderboardClient: () => FanpassLeaderboardClient,
   IngestionClient: () => IngestionClient,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
@@ -1770,6 +1772,99 @@ var DataViewsClient = class {
   }
 };
 
+// src/cohorts.ts
+var CohortLeaderboardClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all cohort definitions
+   */
+  async list(options = {}) {
+    const params = {};
+    if (options.status) params.status = options.status;
+    if (options.limit) params.limit = options.limit;
+    if (options.offset) params.offset = options.offset;
+    const response = await this.http.get(
+      "/cohorts/definitions",
+      params
+    );
+    return response.cohorts || [];
+  }
+  /**
+   * Get a cohort definition by ID
+   */
+  async get(cohortId) {
+    return this.http.get(
+      `/cohorts/definitions/${encodeURIComponent(cohortId)}`
+    );
+  }
+  /**
+   * Get filtered cohort leaderboard with both global and filtered percentiles
+   */
+  async getLeaderboard(cohortId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    if (options.limit) params.limit = options.limit;
+    if (options.top_n) params.top_n = options.top_n;
+    if (options.fresh) params.fresh = "true";
+    return this.http.get(
+      `/cohorts/definitions/${encodeURIComponent(cohortId)}/leaderboard`,
+      params
+    );
+  }
+  /**
+   * Get user's breakdown across all cohorts for spider charts
+   */
+  async getUserBreakdown(userId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    return this.http.get(
+      `/cohorts/users/${encodeURIComponent(userId)}/breakdown`,
+      params
+    );
+  }
+};
+
+// src/fanpass_leaderboard.ts
+var FanpassLeaderboardClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get fanpass leaderboard with composite scores
+   */
+  async getLeaderboard(options = {}) {
+    const params = {};
+    if (options.aggregationRuleId) {
+      params.aggregation_rule_id = options.aggregationRuleId;
+    }
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    if (options.limit) params.limit = options.limit;
+    if (options.top_n) params.top_n = options.top_n;
+    if (options.fresh) params.fresh = "true";
+    return this.http.get(
+      "/passport-v2/fanpass/leaderboard",
+      params
+    );
+  }
+  /**
+   * Get user's comparison across all cohorts (spider chart data)
+   */
+  async getUserComparison(userId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    return this.http.get(
+      `/passport-v2/fanpass/${encodeURIComponent(userId)}/comparison`,
+      params
+    );
+  }
+};
+
 // src/client.ts
 var DocumentsResource = class {
   constructor(http) {
@@ -2065,6 +2160,8 @@ var ProofChain = class _ProofChain {
     this.quests = new QuestsClient(this.http);
     this.schemas = new SchemasClient(this.http);
     this.dataViews = new DataViewsClient(this.http);
+    this.cohorts = new CohortLeaderboardClient(this.http);
+    this.fanpassLeaderboard = new FanpassLeaderboardClient(this.http);
   }
   /**
    * Create a client from environment variables.
@@ -2252,10 +2349,12 @@ var IngestionClient = class {
   AuthorizationError,
   CertificatesResource,
   ChannelsResource,
+  CohortLeaderboardClient,
   DataViewsClient,
   DocumentsResource,
   EndUsersClient,
   EventsResource,
+  FanpassLeaderboardClient,
   IngestionClient,
   NetworkError,
   NotFoundError,

package/dist/index.mjs

@@ -1718,6 +1718,99 @@ var DataViewsClient = class {
   }
 };
 
+// src/cohorts.ts
+var CohortLeaderboardClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all cohort definitions
+   */
+  async list(options = {}) {
+    const params = {};
+    if (options.status) params.status = options.status;
+    if (options.limit) params.limit = options.limit;
+    if (options.offset) params.offset = options.offset;
+    const response = await this.http.get(
+      "/cohorts/definitions",
+      params
+    );
+    return response.cohorts || [];
+  }
+  /**
+   * Get a cohort definition by ID
+   */
+  async get(cohortId) {
+    return this.http.get(
+      `/cohorts/definitions/${encodeURIComponent(cohortId)}`
+    );
+  }
+  /**
+   * Get filtered cohort leaderboard with both global and filtered percentiles
+   */
+  async getLeaderboard(cohortId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    if (options.limit) params.limit = options.limit;
+    if (options.top_n) params.top_n = options.top_n;
+    if (options.fresh) params.fresh = "true";
+    return this.http.get(
+      `/cohorts/definitions/${encodeURIComponent(cohortId)}/leaderboard`,
+      params
+    );
+  }
+  /**
+   * Get user's breakdown across all cohorts for spider charts
+   */
+  async getUserBreakdown(userId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    return this.http.get(
+      `/cohorts/users/${encodeURIComponent(userId)}/breakdown`,
+      params
+    );
+  }
+};
+
+// src/fanpass_leaderboard.ts
+var FanpassLeaderboardClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get fanpass leaderboard with composite scores
+   */
+  async getLeaderboard(options = {}) {
+    const params = {};
+    if (options.aggregationRuleId) {
+      params.aggregation_rule_id = options.aggregationRuleId;
+    }
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    if (options.limit) params.limit = options.limit;
+    if (options.top_n) params.top_n = options.top_n;
+    if (options.fresh) params.fresh = "true";
+    return this.http.get(
+      "/passport-v2/fanpass/leaderboard",
+      params
+    );
+  }
+  /**
+   * Get user's comparison across all cohorts (spider chart data)
+   */
+  async getUserComparison(userId, options = {}) {
+    const params = {};
+    if (options.filters) params.filters = JSON.stringify(options.filters);
+    if (options.country) params.country = options.country;
+    return this.http.get(
+      `/passport-v2/fanpass/${encodeURIComponent(userId)}/comparison`,
+      params
+    );
+  }
+};
+
 // src/client.ts
 var DocumentsResource = class {
   constructor(http) {
@@ -2013,6 +2106,8 @@ var ProofChain = class _ProofChain {
     this.quests = new QuestsClient(this.http);
     this.schemas = new SchemasClient(this.http);
     this.dataViews = new DataViewsClient(this.http);
+    this.cohorts = new CohortLeaderboardClient(this.http);
+    this.fanpassLeaderboard = new FanpassLeaderboardClient(this.http);
   }
   /**
    * Create a client from environment variables.
@@ -2199,10 +2294,12 @@ export {
   AuthorizationError,
   CertificatesResource,
   ChannelsResource,
+  CohortLeaderboardClient,
   DataViewsClient,
   DocumentsResource,
   EndUsersClient,
   EventsResource,
+  FanpassLeaderboardClient,
   IngestionClient,
   NetworkError,
   NotFoundError,

package/package.json

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