Class Tiltify

Tiltify v5 REST client. Prefer the tiltify singleton over new Tiltify().

Index

Constructors

Accessors

Methods

ActivateWebhookEndpoint ClearAuthToken CreateOrUpdateWebhookSubscription CurrentBaseURL DeleteWebhookSubscription DisableAuth DisableErrorLogging EnableErrorLogging FindAuctionHouseByCauseSlug FindAuctionHouseByUserSlug FindCampaign FindTeam FindUser GET GET_Array GET_Paginator GetActiveFundraisingEventMilestones GetAllCurrentFundraisingEvents GetAllTeamCampaigns GetAuctionBids GetAuctionBidsWithCursor GetAuctionHouse GetAuctionItem GetAuctionItems GetAuthMode GetAuthModeAsString GetAuthStatus GetAuthToken GetCampaign GetCampaignDonations GetCampaignFitnessGoals GetCause GetCauseCampaigns GetCauseDonations GetCauseDonorLeaderboard GetCurrentEvents GetCurrentRefreshToken GetCurrentToken GetCurrentUser GetDonationMatches GetEventTeamsFitnessDistanceLeaderboard GetEventTeamsFitnessTimeLeaderboard GetEventUserFitnessDistanceLeaderboard GetEventUserFitnessTimeLeaderboard GetEventUserLeaderboard GetFundraiser GetFundraisingEventsSupportingCampaigns GetLeaderboard GetLeaderboardWithCursor GetMaxRetryDuration GetMilestones GetMode GetNextMilestone GetPoll GetPolls GetRewards GetSchedule GetSourceTag GetTargets GetTeam GetTeamCampaign GetTeamCampaigns GetTeamMembers GetTeamSupportingCampaigns GetTeamUserLeaderboard GetTokenExpiration GetUser GetUserAgent GetUserAndTeamCampaigns GetUserCampaigns IsProxyFallbackEnabled OverrideAuthToken OverrideBaseURL PerformRequest RefreshAuthToken SetCauseApiKey SetCauseMode SetCredentials SetLogger SetLogLevel SetMaxRetries SetMaxRetryDuration SetPublicMode SetSourceTag SetTiltifyTimeout SetUserAgent TestClearCredentials TestOverrideTokenExpiration UseClientAuth UseOriginalBaseURL UseProxy UseProxyWithFallback UseUserAuth WaitForSeconds

Constructors

constructor

new Tiltify(
    __namedParameters?: {
        maxContentLength?: number;
        maxRedirects?: number;
        maxRetryDurationMs?: number;
        timeout?: number;
    },
): Tiltify
Parameters
- __namedParameters: {
      maxContentLength?: number;
      maxRedirects?: number;
      maxRetryDurationMs?: number;
      timeout?: number;
  } = {}
  - OptionalmaxContentLength?: number
  - OptionalmaxRedirects?: number
  - OptionalmaxRetryDurationMs?: number
    
    Optional wall-clock ceiling on total retry duration in ms. Overrides the default 8000ms. Pass 0 to disable and rely on _maxRetries alone.
  - Optionaltimeout?: number
Returns Tiltify
- Defined in packages/tiltify/core/src/client.ts:153

Accessors

`Static`Instance

get Instance(): Tiltify
Returns the singleton instance of the Tiltify client.

Bundler-safe singleton

The instance reference is stored on globalThis behind Symbol.for("@playlive/tiltify-core.instance") rather than on a private static field of this class. Consumer bundlers — notably Vite's optimizeDeps in dev — can pre-bundle each subpath export of a downstream package independently and inline tiltify-core into each pre-bundle. That produces two class Tiltify declarations, each with its own _instance slot, and consumer calls like tiltify.UseProxy(...) land on a different instance than the one the fetcher chain eventually reads from — all requests then run against an unconfigured client and, depending on the caller, fail silently.

Symbol-registry lookup on globalThis collapses those duplicate copies to a single logical instance. Same technique used in @playlive/fundraiser-data/config for its configure() slot; see that module's packageDocumentation block for the fuller story.

Returns Tiltify
- Defined in packages/tiltify/core/src/client.ts:195

Methods

ActivateWebhookEndpoint

ActivateWebhookEndpoint(webhookEndpointID: string): Promise<TiltifyWebhook>
Activates a webhook endpoint by its ID. Requires webhooks:write scope.
Parameters
- webhookEndpointID: string
Returns Promise<TiltifyWebhook>
- Defined in packages/tiltify/core/src/client.ts:2240

ClearAuthToken

ClearAuthToken(): void
Clears the currently stored bearer token, refresh token, and expiration. After calling this, GetAuthStatus returns MISSING.

Returns void
- Defined in packages/tiltify/core/src/client.ts:360

CreateOrUpdateWebhookSubscription

CreateOrUpdateWebhookSubscription(
    webhookEndpointID: string,
    eventID: string,
    eventTypes: (
        | "private:direct:auction_bid_amount_updated"
        | "private:direct:donation_updated"
        | "private:direct:fact_updated"
        | "private:indirect:donation_updated"
        | "private:indirect:fact_updated"
        | "public:direct:auction_bid_amount_updated"
        | "public:direct:donation_updated"
        | "public:direct:fact_updated"
        | "public:indirect:donation_updated"
        | "public:indirect:fact_updated"
    )[],
): Promise<TiltifyWebhookSubscription>
Creates or updates a webhook subscription for a given endpoint and event.
Parameters
- webhookEndpointID: string
- eventID: string
- eventTypes: (
      | "private:direct:auction_bid_amount_updated"
      | "private:direct:donation_updated"
      | "private:direct:fact_updated"
      | "private:indirect:donation_updated"
      | "private:indirect:fact_updated"
      | "public:direct:auction_bid_amount_updated"
      | "public:direct:donation_updated"
      | "public:direct:fact_updated"
      | "public:indirect:donation_updated"
      | "public:indirect:fact_updated"
  )[]
Returns Promise<TiltifyWebhookSubscription>
- Defined in packages/tiltify/core/src/client.ts:2249

CurrentBaseURL

CurrentBaseURL(): string
Returns the currently configured base URL.

Returns string
- Defined in packages/tiltify/core/src/client.ts:528

DeleteWebhookSubscription

DeleteWebhookSubscription(
webhookEndpointID: string,
eventID: string,
): Promise<TiltifyWebhookSubscription>
Deletes a webhook subscription for a given endpoint and event.
Parameters
- webhookEndpointID: string
- eventID: string
Returns Promise<TiltifyWebhookSubscription>
- Defined in packages/tiltify/core/src/client.ts:2271

DisableAuth

DisableAuth(): void
Disables authentication entirely — useful when a proxy handles auth.

Returns void
- Defined in packages/tiltify/core/src/client.ts:301

DisableErrorLogging

DisableErrorLogging(): void
Disables all library logging (equivalent to SetLogLevel("silent")). Errors are still thrown — only the log sink is silenced.

Returns void
- Defined in packages/tiltify/core/src/client.ts:210

EnableErrorLogging

EnableErrorLogging(): void
Re-enables the default logging behavior ("warn" and above).

Returns void
- Defined in packages/tiltify/core/src/client.ts:215

FindAuctionHouseByCauseSlug

FindAuctionHouseByCauseSlug(
causeSlug: string,
auctionHouseSlug: string,
): Promise<TiltifyAuctionHouse | null>
Finds an auction house by cause slug and auction-house slug.
Parameters
- causeSlug: string
- auctionHouseSlug: string
Returns Promise<TiltifyAuctionHouse | null>
- Defined in packages/tiltify/core/src/client.ts:2318

FindAuctionHouseByUserSlug

FindAuctionHouseByUserSlug(
userSlug: string,
auctionHouseSlug: string,
): Promise<TiltifyAuctionHouse | null>
Finds an auction house by user slug and auction-house slug.
Parameters
- userSlug: string
- auctionHouseSlug: string
Returns Promise<TiltifyAuctionHouse | null>
- Defined in packages/tiltify/core/src/client.ts:2304

FindCampaign

FindCampaign(
    userTeamSlug: string,
    campaignSlug: string,
    isTeam?: boolean,
): Promise<TiltifyCampaign | TiltifyTeamCampaign | null>
Finds a campaign by user/team slug and campaign slug. Returns null on 404.
Parameters
- userTeamSlug: string
- campaignSlug: string
- isTeam: boolean = false
Returns Promise<TiltifyCampaign | TiltifyTeamCampaign | null>

See
https://v5api.tiltify.com/api/public/openapi (operation getCampaignBySlugs)
- Defined in packages/tiltify/core/src/client.ts:1587

FindTeam

FindTeam(slug: string): Promise<TiltifyTeam | null>
Finds a team by its slug. Returns null on 404.
Parameters
- slug: string
Returns Promise<TiltifyTeam | null>

See
https://v5api.tiltify.com/api/public/openapi (operation getTeamBySlug)
- Defined in packages/tiltify/core/src/client.ts:1609

FindUser

FindUser(slug: string): Promise<TiltifyUser | null>
Finds a user by their slug. Returns null on 404.
Parameters
- slug: string
Returns Promise<TiltifyUser | null>

See
https://v5api.tiltify.com/api/public/openapi (operation getUserBySlug)
- Defined in packages/tiltify/core/src/client.ts:1621

GET

GET<T>(
    endpoint: string,
    limit?: number | null,
    cursor?: string | null,
    cursorMode?: "before" | "after",
): Promise<{ data: T; error?: string; metadata: TiltifyMetadata }>
Helper for calling the Tiltify v5 API with optional pagination parameters. Tiltify error responses are returned as data rather than thrown.
Type Parameters
- T
Parameters
- endpoint: string
- limit: number | null = 100
- cursor: string | null = null
- cursorMode: "before" | "after" = "after"
Returns Promise<{ data: T; error?: string; metadata: TiltifyMetadata }>
Example
```
const { data, metadata } = await tiltify.GET<TiltifyDonation[]>(
  "public/campaigns/my-id/donations",
  50,
);
```
- Defined in packages/tiltify/core/src/client.ts:1337

GET_Array

GET_Array<T>(endpoint: string, max?: number, batchLimit?: number): Promise<T[]>
Auto-paginating wrapper around GET that accumulates all results into a single array.
Type Parameters
- T
Parameters
- endpoint: string
- max: number = Number.MAX_VALUE
- batchLimit: number = 100
Returns Promise<T[]>
Example
```
const donations = await tiltify.GET_Array<TiltifyDonation>(
  "public/campaigns/my-id/donations",
);
```
- Defined in packages/tiltify/core/src/client.ts:1467

GET_Paginator

GET_Paginator<T>(
    endpoint: string,
    dataCallback: (
        data: T[],
        metadata: TiltifyMetadata,
    ) => Promise<string | null>,
    limit?: number,
): Promise<void>
A DIY paginator. Calls the provided async callback with each page of data. The callback must return a cursor string to continue paginating, or null to stop.
Type Parameters
- T
Parameters
- endpoint: string
- dataCallback: (data: T[], metadata: TiltifyMetadata) => Promise<string | null>
- limit: number = 100
Returns Promise<void>
Example
```
await tiltify.GET_Paginator<TiltifyDonation>(
  "public/campaigns/my-id/donations",
  async (donations, metadata) => {
    await processBatch(donations);
    return metadata.after ?? null;
  },
);
```
- Defined in packages/tiltify/core/src/client.ts:1431

GetActiveFundraisingEventMilestones

GetActiveFundraisingEventMilestones(
fundraisingEventID: string,
): Promise<TiltifyFactMilestone[] | null>
Get the currently active milestones for a fundraising event by its public id — the same UUID returned by GET /public/fundraising_events/{id} and referenced throughout the Tiltify REST API (/supporting_events, /user_leaderboard, …).

This is a proxy-only call. Tiltify's public REST API has no milestones endpoint for a fundraising event — milestones exist only for campaigns, team campaigns, personal campaigns, and facts (and /public/facts/:fact_id/milestones 404s for fundraising-event ids). The FE-level list is reachable only through the GraphQL endpoint tiltify.com's own landing pages use, which browsers cannot call from a Play Live surface (CORS + Cloudflare bot-scoring).

The proxy therefore fills the gap at GET /public/fundraising_events/:fundraising_event_id/milestones, resolving the fact via GraphQL, filtering active === true server-side, and returning a Tiltify REST-shaped { data, metadata } envelope. Requires UseProxy to have been called — there is no direct fallback.

The proxy scopes this route to St. Jude: a fundraising event owned by any other cause is refused with a 403, since fact ids are global and the route would otherwise act as an open relay for Tiltify's GraphQL gateway.

Public / unauthenticated route: no Authorization header is sent and the proxy never returns inactive milestones. This method also re-filters active === true client-side as defence-in-depth in case a future proxy version drifts.

The returned items are field-compatible with the REST TiltifyMilestone from GetMilestones, minus inserted_at / updated_at / legacy_id (the upstream GraphQL fragment does not project those).
Parameters
- fundraisingEventID: string
  The fundraising event's public id (UUID).
Returns Promise<TiltifyFactMilestone[] | null>
Ordered array of active milestones, or null when no fundraising event matches the id (the proxy answers 404 with Tiltify's own error envelope, matching GetCampaign's not-found convention). An empty array is meaningful and distinct: the event exists but currently has no active milestones.
Throws
HTTP_ERROR on non-2xx, non-404 proxy responses — including the 422 the proxy returns for a malformed (non-UUID) id, and the 403 it returns for a fundraising event that is not a St. Jude event.
Example
```
tiltify.UseProxy("prod");
const active = await tiltify.GetActiveFundraisingEventMilestones(
  "7d3ee5c9-684a-47ae-bb88-ced83b19fa4e",
);
if (active === null) {
  // no such fundraising event
}
```
- Defined in packages/tiltify/core/src/client.ts:1870

GetAllCurrentFundraisingEvents

GetAllCurrentFundraisingEvents(
    limit?: number,
    cursor?: string | null,
): Promise<
    {
        data: TiltifyFundraisingEvent[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
Gets all current fundraising events at the cause level with optional pagination.
Parameters
- limit: number = 100
- cursor: string | null = null
Returns Promise<
    {
        data: TiltifyFundraisingEvent[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
- Defined in packages/tiltify/core/src/client.ts:1694

GetAllTeamCampaigns

GetAllTeamCampaigns(): Promise<TiltifyTeamCampaign[]>
Gets all team campaigns for the current cause.

Returns Promise<TiltifyTeamCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1741

GetAuctionBids

GetAuctionBids(
    auctionHouseID: string,
    auctionItemID: string,
    limit?: number,
): Promise<TiltifyAuctionBid[]>
Gets bids for a given auction item.
Parameters
- auctionHouseID: string
- auctionItemID: string
- Optionallimit: number
Returns Promise<TiltifyAuctionBid[]>
- Defined in packages/tiltify/core/src/client.ts:2384

GetAuctionBidsWithCursor

GetAuctionBidsWithCursor(
    auctionHouseID: string,
    auctionItemID: string,
    limit?: number,
    cursor?: string | null,
    cursorMode?: "before" | "after",
): Promise<
    { data: TiltifyAuctionBid[]; error?: string; metadata: TiltifyMetadata },
>
Gets bids for an auction item with pagination metadata.
Parameters
- auctionHouseID: string
- auctionItemID: string
- limit: number = 100
- cursor: string | null = null
- cursorMode: "before" | "after" = "after"
Returns Promise<
{ data: TiltifyAuctionBid[]; error?: string; metadata: TiltifyMetadata },
>
- Defined in packages/tiltify/core/src/client.ts:2396

GetAuctionHouse

GetAuctionHouse(auctionHouseID: string): Promise<TiltifyAuctionHouse | null>
Gets an auction house by its ID.
Parameters
- auctionHouseID: string
Returns Promise<TiltifyAuctionHouse | null>
- Defined in packages/tiltify/core/src/client.ts:2296

GetAuctionItem

GetAuctionItem(
auctionHouseID: string,
auctionItemID: string,
): Promise<TiltifyAuctionItem | null>
Gets a single auction item by ID.
Parameters
- auctionHouseID: string
- auctionItemID: string
Returns Promise<TiltifyAuctionItem | null>
- Defined in packages/tiltify/core/src/client.ts:2370

GetAuctionItems

GetAuctionItems(
    auctionHouseID: string,
    options?: {
        created_after?: string;
        created_before?: string;
        limit?: number;
        status?: TiltifyAuctionItemStatus;
        updated_after?: string;
        updated_before?: string;
    },
): Promise<TiltifyAuctionItem[]>
Gets auction items for a given auction house.
Parameters
- auctionHouseID: string
- Optionaloptions: {
      created_after?: string;
      created_before?: string;
      limit?: number;
      status?: TiltifyAuctionItemStatus;
      updated_after?: string;
      updated_before?: string;
  }
Returns Promise<TiltifyAuctionItem[]>
- Defined in packages/tiltify/core/src/client.ts:2332

GetAuthMode

GetAuthMode(): TILTIFY_AUTH_MODE
Returns the current authentication mode.

Returns TILTIFY_AUTH_MODE
- Defined in packages/tiltify/core/src/client.ts:336

GetAuthModeAsString

GetAuthModeAsString(): string
Returns the current authentication mode as a string.

Returns string
- Defined in packages/tiltify/core/src/client.ts:341

GetAuthStatus

GetAuthStatus(): TILTIFY_AUTH_STATUS
Returns the freshness status of the currently stored access token.

Returns TILTIFY_AUTH_STATUS
- Defined in packages/tiltify/core/src/client.ts:346

GetAuthToken

GetAuthToken(
    clientID?: string | undefined,
    clientSecret?: string | undefined,
    scope?: TiltifyOAuthScope,
): Promise<string | null>
Fetches an OAuth access token from Tiltify using the client_credentials grant. Only valid in CLIENT auth mode.
- DISABLED mode → returns null (proxy-handled auth).
- USER mode → throws (call OverrideAuthToken instead).
Parameters
- clientID: string | undefined = undefined
  Falls back to process.env.TILTIFY_CLIENT_ID.
- clientSecret: string | undefined = undefined
  Falls back to process.env.TILTIFY_SECRET.
- scope: TiltifyOAuthScope = "cause"
  OAuth scope to request. Defaults to "cause".
Returns Promise<string | null>
The bearer token string, or null if auth is disabled.
Throws
On missing credentials, rejected credentials, or wrong mode.

See
https://v5api.tiltify.com/api/public/openapi
Example
```
tiltify.UseClientAuth();
await tiltify.GetAuthToken(process.env.TILTIFY_CLIENT_ID, process.env.TILTIFY_SECRET);
```
- Defined in packages/tiltify/core/src/client.ts:646

GetCampaign

GetCampaign(
campaignID: string,
isTeam?: boolean,
): Promise<TiltifyCampaign | TiltifyTeamCampaign | null>
Gets a campaign by its ID.
Parameters
- campaignID: string
  The campaign ID.
- isTeam: boolean = false
  If true, fetches a team campaign.
Returns Promise<TiltifyCampaign | TiltifyTeamCampaign | null>
The campaign data, or null if not found.
See
https://v5api.tiltify.com/api/public/openapi (operation getCampaign)
Example
```
const campaign = await tiltify.GetCampaign("abc-123");
```
- Defined in packages/tiltify/core/src/client.ts:1565

GetCampaignDonations

GetCampaignDonations(
    campaignID: string,
    isTeam?: boolean,
    count?: number,
    completed_before?: string | Date | null,
    completed_after?: string | Date | null,
): Promise<TiltifyDonation[]>
Gets donations for a given campaign with optional date range filters.
Parameters
- campaignID: string
- isTeam: boolean = false
- count: number = 10
- completed_before: string | Date | null = null
- completed_after: string | Date | null = null
Returns Promise<TiltifyDonation[]>
- Defined in packages/tiltify/core/src/client.ts:2017

GetCampaignFitnessGoals

GetCampaignFitnessGoals(
    campaignID: string,
    isTeam?: boolean,
    max?: number,
): Promise<TiltifyFitnessGoal[]>
Gets the fitness goals for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
- max: number = 20
Returns Promise<TiltifyFitnessGoal[]>
- Defined in packages/tiltify/core/src/client.ts:2153

GetCause

GetCause(causeID: string): Promise<TiltifyCause | null>
Returns a cause by its ID. Returns null if not found.
Parameters
- causeID: string
Returns Promise<TiltifyCause | null>
- Defined in packages/tiltify/core/src/client.ts:1784

GetCauseCampaigns

GetCauseCampaigns(all?: boolean): Promise<TiltifyCampaign[]>
Returns all cause campaigns, automatically handling pagination.
Parameters
- all: boolean = true
Returns Promise<TiltifyCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1792

GetCauseDonations

GetCauseDonations(
    count?: number,
    created_before?: string | null,
    created_after?: string | null,
): Promise<TiltifyDonation[]>
Gets donations for the current cause. Requires cause mode + API key.
Parameters
- count: number = 10
- created_before: string | null = null
- created_after: string | null = null
Returns Promise<TiltifyDonation[]>
- Defined in packages/tiltify/core/src/client.ts:2050

GetCauseDonorLeaderboard

GetCauseDonorLeaderboard(
    causeID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the donor leaderboard for a given cause.
Parameters
- causeID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = Number.MAX_VALUE
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2129

GetCurrentEvents

GetCurrentEvents(): Promise<
    {
        data: TiltifyFundraisingEvent[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
Gets all current St. Jude fundraising events.

Returns Promise<
    {
        data: TiltifyFundraisingEvent[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
- Defined in packages/tiltify/core/src/client.ts:1683

GetCurrentRefreshToken

GetCurrentRefreshToken(): string | null
Returns the currently stored OAuth refresh token, or null if none has been provided. Refresh tokens are only set by callers via OverrideAuthToken or rotated automatically by RefreshAuthToken.

Returns string | null
- Defined in packages/tiltify/core/src/client.ts:423

GetCurrentToken

GetCurrentToken(): string | null
Returns the current bearer token string, or null if not authenticated.

Returns string | null
- Defined in packages/tiltify/core/src/client.ts:413

GetCurrentUser

GetCurrentUser(): Promise<TiltifyUser>
Returns the user associated with the current OAuth access token (USER mode only).

Returns Promise<TiltifyUser>
- Defined in packages/tiltify/core/src/client.ts:2217

GetDonationMatches

GetDonationMatches(campaignID: string): Promise<TiltifyDonationMatch[]>
Gets up to 3 active donation matches for a given campaign.
Parameters
- campaignID: string
Returns Promise<TiltifyDonationMatch[]>
- Defined in packages/tiltify/core/src/client.ts:2227

GetEventTeamsFitnessDistanceLeaderboard

GetEventTeamsFitnessDistanceLeaderboard(
    fundraisingEventID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the top teams by fitness distance for a given fundraising event.
Parameters
- fundraisingEventID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = 20
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2165

GetEventTeamsFitnessTimeLeaderboard

GetEventTeamsFitnessTimeLeaderboard(
    fundraisingEventID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the top teams by fitness time for a given fundraising event.
Parameters
- fundraisingEventID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = 20
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2178

GetEventUserFitnessDistanceLeaderboard

GetEventUserFitnessDistanceLeaderboard(
    fundraisingEventID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the top users by fitness distance for a given fundraising event.
Parameters
- fundraisingEventID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = 20
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2204

GetEventUserFitnessTimeLeaderboard

GetEventUserFitnessTimeLeaderboard(
    fundraisingEventID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the top users by fitness time for a given fundraising event.
Parameters
- fundraisingEventID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = 20
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2191

GetEventUserLeaderboard

GetEventUserLeaderboard(
fundraisingEventID: string,
count?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the user leaderboard for a given fundraising event.
Parameters
- fundraisingEventID: string
- count: number = 20
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2142

GetFundraiser

GetFundraiser(fundraiserID: string): Promise<TiltifyFundraisingEvent>
Gets a fundraising event by its ID.
Parameters
- fundraiserID: string
Returns Promise<TiltifyFundraisingEvent>

See
https://v5api.tiltify.com/api/public/openapi (operation getFundraisingEvent)
- Defined in packages/tiltify/core/src/client.ts:1676

GetFundraisingEventsSupportingCampaigns

GetFundraisingEventsSupportingCampaigns(
fundraisingEventID: string,
limit?: number,
): Promise<TiltifyCampaign[]>
Gets all campaigns supporting a given fundraising event.
Parameters
- fundraisingEventID: string
- limit: number = 100
Returns Promise<TiltifyCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1707

GetLeaderboard

GetLeaderboard(
    campaignID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    isTeam?: boolean,
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the donor leaderboard for a given campaign.
Parameters
- campaignID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- isTeam: boolean = false
- max: number = Number.MAX_VALUE
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2086

GetLeaderboardWithCursor

GetLeaderboardWithCursor(
    campaignID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    isTeam?: boolean,
    max?: number,
    cursor?: string | null,
): Promise<
    {
        data: TiltifyLeaderboardEntry[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
Gets the donor leaderboard for a given campaign, returning the raw paginated response.
Parameters
- campaignID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- isTeam: boolean = false
- max: number = Number.MAX_VALUE
- cursor: string | null = null
Returns Promise<
    {
        data: TiltifyLeaderboardEntry[];
        error?: string;
        metadata: TiltifyMetadata;
    },
>
- Defined in packages/tiltify/core/src/client.ts:2100

GetMaxRetryDuration

GetMaxRetryDuration(): number
Returns the current retry-duration cap (ms). 0 means disabled.

Returns number
- Defined in packages/tiltify/core/src/client.ts:594

GetMilestones

GetMilestones(campaignID: string, isTeam?: boolean): Promise<TiltifyMilestone[]>
Gets the milestones for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
Returns Promise<TiltifyMilestone[]>
- Defined in packages/tiltify/core/src/client.ts:1807

GetMode

GetMode(): "public" | "cause"
Returns the current API mode ("public" or "cause").

Returns "public" | "cause"
- Defined in packages/tiltify/core/src/client.ts:296

GetNextMilestone

GetNextMilestone(
    campaignID: string,
    isTeam?: boolean,
    amountRaised?: number | null,
): Promise<TiltifyMilestone | null>
Gets the next unachieved milestone for a campaign based on amount raised.
Parameters
- campaignID: string
- isTeam: boolean = false
- amountRaised: number | null = null
Returns Promise<TiltifyMilestone | null>
- Defined in packages/tiltify/core/src/client.ts:1951

GetPoll

GetPoll(
    campaignID: string,
    pollID: string,
    isTeam?: boolean,
): Promise<TiltifyPoll | null>
Gets a single poll by ID for a given campaign.
Parameters
- campaignID: string
- pollID: string
- isTeam: boolean = false
Returns Promise<TiltifyPoll | null>
- Defined in packages/tiltify/core/src/client.ts:1987

GetPolls

GetPolls(campaignID: string, isTeam?: boolean): Promise<TiltifyPoll[]>
Gets all polls for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
Returns Promise<TiltifyPoll[]>
- Defined in packages/tiltify/core/src/client.ts:1980

GetRewards

GetRewards(campaignID: string, isTeam?: boolean): Promise<TiltifyReward[]>
Gets the rewards for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
Returns Promise<TiltifyReward[]>
- Defined in packages/tiltify/core/src/client.ts:2010

GetSchedule

GetSchedule(campaignID: string, isTeam?: boolean): Promise<TiltifySchedule[]>
Gets the schedule for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
Returns Promise<TiltifySchedule[]>
- Defined in packages/tiltify/core/src/client.ts:2003

GetSourceTag

GetSourceTag(): string
Returns the currently configured source-tag value.

Returns string
- Defined in packages/tiltify/core/src/client.ts:489

GetTargets

GetTargets(campaignID: string, isTeam?: boolean): Promise<TiltifyTarget[]>
Gets the donation targets for a given campaign.
Parameters
- campaignID: string
- isTeam: boolean = false
Returns Promise<TiltifyTarget[]>
- Defined in packages/tiltify/core/src/client.ts:1800

GetTeam

GetTeam(teamID: string): Promise<TiltifyTeam | null>
Gets a team by its ID. Returns null on 404.
Parameters
- teamID: string
Returns Promise<TiltifyTeam | null>

See
https://v5api.tiltify.com/api/public/openapi (operation getTeam)
- Defined in packages/tiltify/core/src/client.ts:1645

GetTeamCampaign

GetTeamCampaign(
teamSlugID: string,
campaignSlugID?: string | null,
): Promise<TiltifyTeamCampaign | TiltifyTeamCampaign[]>
Gets a specific team campaign or all campaigns for a team.
Parameters
- teamSlugID: string
- campaignSlugID: string | null = null
Returns Promise<TiltifyTeamCampaign | TiltifyTeamCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1725

GetTeamCampaigns

GetTeamCampaigns(
    teamID: string,
    status?: "published" | "retired",
    supportingType?: TiltifyCampaignSupportableType,
): Promise<TiltifyTeamCampaign[]>
Gets all campaigns for a given team ID with optional status / supporting filters.
Parameters
- teamID: string
- Optionalstatus: "published" | "retired"
- OptionalsupportingType: TiltifyCampaignSupportableType
Returns Promise<TiltifyTeamCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1760

GetTeamMembers

GetTeamMembers(
    teamID: string,
    limit?: number,
    before?: string,
    after?: string,
): Promise<
    { data: TiltifyTeamMember[]; error?: string; metadata: TiltifyMetadata },
>
Gets the members of a team.
Parameters
- teamID: string
- Optionallimit: number
- Optionalbefore: string
- Optionalafter: string
Returns Promise<
{ data: TiltifyTeamMember[]; error?: string; metadata: TiltifyMetadata },
>

See
https://v5api.tiltify.com/api/public/openapi (operation getTeamMembers)
- Defined in packages/tiltify/core/src/client.ts:1657

GetTeamSupportingCampaigns

GetTeamSupportingCampaigns(teamCampaignID: string): Promise<TiltifyCampaign[]>
Gets all campaigns supporting a given team campaign.
Parameters
- teamCampaignID: string
Returns Promise<TiltifyCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1718

GetTeamUserLeaderboard

GetTeamUserLeaderboard(
    campaignID: string,
    timeType?: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd",
    max?: number,
): Promise<TiltifyLeaderboardEntry[]>
Gets the user leaderboard for a given team campaign.
Parameters
- campaignID: string
- timeType: "all" | "daily" | "weekly" | "monthly" | "yearly" | "ytd" = "all"
- max: number = Number.MAX_VALUE
Returns Promise<TiltifyLeaderboardEntry[]>
- Defined in packages/tiltify/core/src/client.ts:2116

GetTokenExpiration

GetTokenExpiration(): number
Returns the current token expiration timestamp in milliseconds.

Returns number
- Defined in packages/tiltify/core/src/client.ts:408

GetUser

GetUser(id: string): Promise<TiltifyUser | null>
Gets a user by their ID.
Parameters
- id: string
Returns Promise<TiltifyUser | null>

See
https://v5api.tiltify.com/api/public/openapi (operation getUser)
- Defined in packages/tiltify/core/src/client.ts:1633

GetUserAgent

GetUserAgent(): string
Returns the currently configured outbound User-Agent string.

Returns string
- Defined in packages/tiltify/core/src/client.ts:518

GetUserAndTeamCampaigns

GetUserAndTeamCampaigns(
userID: string,
): Promise<(TiltifyPersonalCampaign | TiltifyTeamCampaign)[]>
Lists all campaigns and team campaigns for a given user ID.
Parameters
- userID: string
Returns Promise<(TiltifyPersonalCampaign | TiltifyTeamCampaign)[]>
- Defined in packages/tiltify/core/src/client.ts:1751

GetUserCampaigns

GetUserCampaigns(userID: string): Promise<TiltifyPersonalCampaign[]>
Gets all personal campaigns for a given user ID.
Parameters
- userID: string
Returns Promise<TiltifyPersonalCampaign[]>
- Defined in packages/tiltify/core/src/client.ts:1746

IsProxyFallbackEnabled

IsProxyFallbackEnabled(): boolean
Returns whether proxy fallback mode is currently enabled.

Returns boolean
- Defined in packages/tiltify/core/src/client.ts:475

OverrideAuthToken

OverrideAuthToken(
    token: string,
    expiration: number,
    refreshToken?: string | null,
): void
Manually sets the current bearer token, its expiration, and (optionally) a refresh token. The canonical way to authenticate in USER auth mode.
Parameters
- token: string
  Full Authorization-header value (e.g. "Bearer eyJ...").
- expiration: number
  Milliseconds timestamp at which the token expires.
- OptionalrefreshToken: string | null
  OAuth refresh token. Pass undefined to leave any previously stored refresh token in place; pass null to explicitly clear it.
Returns void
Example
```
tiltify.UseUserAuth();
tiltify.SetCredentials(clientID, clientSecret);
tiltify.OverrideAuthToken(`Bearer ${accessToken}`, Date.now() + expiresInMs, refreshToken);
```
- Defined in packages/tiltify/core/src/client.ts:399

OverrideBaseURL

OverrideBaseURL(url: string): void
Overrides the base URL used for all API requests.
Parameters
- url: string
Returns void
- Defined in packages/tiltify/core/src/client.ts:523

PerformRequest

PerformRequest<T>(
    endpoint: string,
    method?: string,
    retry?: number,
    scope?: TiltifyOAuthScope,
    body?: string | null,
    handleError?: boolean,
): Promise<{ data: T; status: number }>
Type Parameters
- T
Parameters
- endpoint: string
- method: string = "get"
- Optionalretry: number
- scope: TiltifyOAuthScope = "cause"
- body: string | null = null
- handleError: boolean = true
Returns Promise<{ data: T; status: number }>
- Defined in packages/tiltify/core/src/client.ts:920

RefreshAuthToken

RefreshAuthToken(): Promise<string | null>
Exchanges the currently stored refresh token for a fresh access token. Only valid in USER auth mode.

Returns Promise<string | null>
The new bearer token string, or null if auth is disabled.
Throws
If not in USER mode, no refresh token has been stored, client credentials are missing (direct mode only), or the OAuth server rejects the refresh request.
Example
```
tiltify.UseUserAuth();
tiltify.UseProxy("prod");
tiltify.OverrideAuthToken(`Bearer ${at}`, exp, refreshToken);
await tiltify.RefreshAuthToken();
```
- Defined in packages/tiltify/core/src/client.ts:726

SetCauseApiKey

SetCauseApiKey(apiKey: string): void
Stores the Cause API key sent as Cause-Api-Key on cause-mode requests.
Parameters
- apiKey: string
  The Tiltify-issued cause API key.
Returns void
Example
```
tiltify.SetCauseMode();
tiltify.SetCauseApiKey(process.env.CAUSE_API_KEY);
```
- Defined in packages/tiltify/core/src/client.ts:270

SetCauseMode

SetCauseMode(): void
Switches to the cause API namespace (requires SetCauseApiKey).

Returns void
- Defined in packages/tiltify/core/src/client.ts:291

SetCredentials

SetCredentials(clientId: string, clientSecret: string): void
Sets the client ID + secret used for client-credential auth. Takes precedence over TILTIFY_CLIENT_ID / TILTIFY_SECRET env vars.
Parameters
- clientId: string
  Tiltify application client ID.
- clientSecret: string
  Tiltify application client secret.
Returns void
Example
```
tiltify.UseClientAuth();
tiltify.SetCredentials("my-client-id", "my-client-secret");
await tiltify.GetAuthToken();
```
- Defined in packages/tiltify/core/src/client.ts:285

SetLogger

SetLogger(fn: LogFn): void
Replaces the built-in console.*-based logger with a custom sink — for example to forward logs to Sentry, pino, or any structured logger.
Parameters
- fn: LogFn
  A LogFn that handles (level, scope, message, ctx).
Returns void
Example
```
tiltify.SetLogger((level, scope, message, ctx) => {
  myLogger[level]({ scope, ctx }, message);
});
```
- Defined in packages/tiltify/core/src/client.ts:242

SetLogLevel

SetLogLevel(level: LogLevel): void
Sets the minimum log level. Anything below the chosen level is dropped. Use "silent" to suppress all logging.
Parameters
- level: LogLevel
  One of "debug" | "info" | "warn" | "error" | "silent".
Returns void
Example
```
tiltify.SetLogLevel("debug"); // see everything
tiltify.SetLogLevel("silent"); // see nothing
```
- Defined in packages/tiltify/core/src/client.ts:228

SetMaxRetries

SetMaxRetries(maxRetries: number): void
Sets the maximum retry count for transient failures (default 5).

PerformRequest retries 401/502/5xx responses and AbortError timeouts up to this many times, with 0.5s backoff between attempts. Each attempt is a fresh fetch() and so produces its own OTEL undici span — lowering this is the right knob for "best effort" Lambdas (e.g. periodic ticks, fire-and-forget snapshots) where a single failed read is cheap and the next invocation will retry anyway, and where the per-attempt OTEL error span volume is unwanted dashboard noise.

Pass 0 to disable retries entirely.
Parameters
- maxRetries: number
Returns void
- Defined in packages/tiltify/core/src/client.ts:558

SetMaxRetryDuration

SetMaxRetryDuration(ms: number): void
Sets a wall-clock ceiling on the total time a single PerformRequest (including all retry sleeps) may spend before short-circuiting with the last observed error. Defaults to 0 (disabled) so _maxRetries alone governs retry behavior — opt in from short-timeout callers such as API-Gateway lambdas that would otherwise burn ~15s on a full exponential-backoff chain while their client has already timed out.

The cap is checked before each retry sleep; a sleep that would push Date.now() past the deadline aborts the retry loop and throws the response's error immediately. Explicit Retry-After headers are still honoured whenever they fit within the remaining budget.

Pass 0 to disable the cap.
Parameters
- ms: number
  Maximum retry budget in milliseconds.
Returns void
- Defined in packages/tiltify/core/src/client.ts:584

SetPublicMode

SetPublicMode(): void
Switches to the public API namespace (default).

Returns void
- Defined in packages/tiltify/core/src/client.ts:258

SetSourceTag

SetSourceTag(source: string): void
Overrides the value sent in the source-tagging header (X-Source by default).
Parameters
- source: string
  The source identifier (e.g. an app name or build ID).
Returns void
- Defined in packages/tiltify/core/src/client.ts:484

SetTiltifyTimeout

SetTiltifyTimeout(timeout: number): void
Sets the per-request timeout in milliseconds (default 5000).
Parameters
- timeout: number
Returns void
- Defined in packages/tiltify/core/src/client.ts:540

SetUserAgent

SetUserAgent(userAgent: string): void
Overrides the outbound User-Agent header. Useful when a consumer wants Tiltify-side logs (and Cloudflare bot-scoring) to attribute traffic to a specific PLAY LIVE surface instead of the generic library default. The value is sent verbatim on every fetch — token mints, refresh exchanges, and all REST calls.
Parameters
- userAgent: string
  A non-empty UA string. Empty / whitespace-only values are ignored so consumers cannot accidentally fall back to Node's bare node default by passing "".
Returns void
Example
```
tiltify.SetUserAgent("playlive-rest-api/1.0 (+https://playlive.experience.stjude.org)");
```
- Defined in packages/tiltify/core/src/client.ts:506

TestClearCredentials

TestClearCredentials(): void
Internal
Test helper: clears credentials set via SetCredentials, reverting to env var fallback.

Returns void
- Defined in packages/tiltify/core/src/client.ts:372

TestOverrideTokenExpiration

TestOverrideTokenExpiration(expiration: number): void
Internal
Test helper: manually overrides the token expiration time.
Parameters
- expiration: number
  A Date-compatible milliseconds timestamp.
Returns void
- Defined in packages/tiltify/core/src/client.ts:382

UseClientAuth

UseClientAuth(): void
Switches to client-credential auth mode. Reads TILTIFY_CLIENT_ID and TILTIFY_SECRET from process.env unless SetCredentials has been called.

Returns void
- Defined in packages/tiltify/core/src/client.ts:310

UseOriginalBaseURL

UseOriginalBaseURL(): void
Resets the base URL back to the default Tiltify v5 API URL and clears proxy flags.

Returns void
- Defined in packages/tiltify/core/src/client.ts:533

UseProxy

UseProxy(envOrURL?: string, source?: string): void
Configures the library to use a Tiltify proxy. Disables direct auth and overrides the base URL. Also clears any leftover bearer token stashed by a previous GetAuthToken / OverrideAuthToken call — the proxy handles auth server-side, and leaving a stale (or cause-scoped) bearer on the singleton would poison downstream requests. USER mode is preserved so consumers driving their own OAuth flow keep their token.
Parameters
- envOrURL: string = PROXY_URLS.prod
  Either an env shorthand ("dev" | "qa" | "prod") or an explicit proxy base URL. Defaults to the production St. Jude proxy.
- Optionalsource: string
  Optional value for the source-tagging header.
Returns void
Example
```
tiltify.UseProxy("https://your-proxy.example.com/api/");
tiltify.SetPublicMode();
const campaign = await tiltify.FindCampaign("team", "campaign");
```
- Defined in packages/tiltify/core/src/client.ts:443

UseProxyWithFallback

UseProxyWithFallback(source?: string): void
Enables proxy mode with an automatic env fallback chain (prod → qa → dev). Transient or server-side failures advance the chain; 4xx responses propagate immediately.
Parameters
- Optionalsource: string
  Optional source-tag header value (see UseProxy).
Returns void
Example
```
tiltify.UseProxyWithFallback();
const user = await tiltify.FindUser("some-user-slug");
```
- Defined in packages/tiltify/core/src/client.ts:469

UseUserAuth

UseUserAuth(): void
Switches to user OAuth auth mode.

In this mode the library does not perform the initial OAuth code-exchange — the consumer is responsible for that step (typically on a server they control) and pushes the resulting bearer token into the client via OverrideAuthToken. If the consumer also supplies a refresh token, the library will transparently exchange it for a fresh access token when the current one expires (see RefreshAuthToken).

Returns void
Example
```
tiltify.UseUserAuth();
tiltify.UseProxy();
tiltify.SetCredentials(clientID, clientSecret);
tiltify.OverrideAuthToken(`Bearer ${accessToken}`, expiresAtMs, refreshToken);
const me = await tiltify.GetCurrentUser();
```
- Defined in packages/tiltify/core/src/client.ts:331

WaitForSeconds

WaitForSeconds(seconds: number): Promise<void>
Waits asynchronously for the given number of seconds. Useful for Tiltify rate-limit handling.
Parameters
- seconds: number
  Number of seconds to wait.
Returns Promise<void>
- Defined in packages/tiltify/core/src/client.ts:604

Class Tiltify

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

OptionalmaxContentLength?: number

OptionalmaxRedirects?: number

OptionalmaxRetryDurationMs?: number

Optionaltimeout?: number

Returns Tiltify

Accessors

StaticInstance

Bundler-safe singleton

Returns Tiltify

Methods

ActivateWebhookEndpoint

Parameters

Returns Promise<TiltifyWebhook>

ClearAuthToken

Returns void

CreateOrUpdateWebhookSubscription

Parameters

Returns Promise<TiltifyWebhookSubscription>

CurrentBaseURL

Returns string

DeleteWebhookSubscription

Parameters

Returns Promise<TiltifyWebhookSubscription>

DisableAuth

Returns void

DisableErrorLogging

Returns void

EnableErrorLogging

Returns void

FindAuctionHouseByCauseSlug

Parameters

Returns Promise<TiltifyAuctionHouse | null>

FindAuctionHouseByUserSlug

Parameters

Returns Promise<TiltifyAuctionHouse | null>

FindCampaign

Parameters

Returns Promise<TiltifyCampaign | TiltifyTeamCampaign | null>

See

FindTeam

Parameters

Returns Promise<TiltifyTeam | null>

See

FindUser

Parameters

Returns Promise<TiltifyUser | null>

See

GET

Type Parameters

Parameters

Returns Promise<{ data: T; error?: string; metadata: TiltifyMetadata }>

Example

GET_Array

Type Parameters

Parameters

Returns Promise<T[]>

Example

GET_Paginator

Type Parameters

Parameters

Returns Promise<void>

Example

GetActiveFundraisingEventMilestones

Parameters

Returns Promise<TiltifyFactMilestone[] | null>

Throws

Example

GetAllCurrentFundraisingEvents

Parameters

Returns Promise< { data: TiltifyFundraisingEvent[]; error?: string; metadata: TiltifyMetadata; },>

GetAllTeamCampaigns

Returns Promise<TiltifyTeamCampaign[]>

`Optional`maxContentLength?: number

`Optional`maxRedirects?: number

`Optional`maxRetryDurationMs?: number

`Optional`timeout?: number

`Static`Instance

Returns Promise<
{
data: TiltifyFundraisingEvent[];
error?: string;
metadata: TiltifyMetadata;
},
>

Returns Promise<
{ data: TiltifyAuctionBid[]; error?: string; metadata: TiltifyMetadata },
>

Returns Promise<
{
data: TiltifyFundraisingEvent[];
error?: string;
metadata: TiltifyMetadata;
},
>