@playlive/tiltify-graphql
    Preparing search index...

    Class TiltifyGraphQL

    Thin wrapper around the public Tiltify GraphQL endpoint (https://api.tiltify.com/). Every method returns the unwrapped data for the corresponding operation and throws on HTTP errors or GraphQL errors.

    The endpoint accepts unauthenticated requests for every operation defined here. If you need authenticated queries (e.g. get_authed_user on dashboardapi.tiltify.com) pass an Authorization header via options.headers and override endpoint in the constructor.

    import { TiltifyGraphQL } from "@playlive/tiltify-graphql";

    const gql = new TiltifyGraphQL();
    const cause = await gql.getCauseBySlug("stjude");
    const top = await gql.getFactTopDonation(cause!.causeFactId);

    https://api.tiltify.com — the public GraphQL endpoint.

    Index
    constructor
    clientLibrary endpoint fetchImpl headers
    getAllFactDonations getCauseAndFundraisingEventBySlug getCauseBySlug getCauseLeaderboards getCurrentMissions getFactByVanityAndSlug getFactDonations getFactFitnessLeaderboards getFactLeaderboards getFactMilestones getFactTopDonation getFundraisingEventLeaderboards getLatestBadges getUserBadges getUserBySlug query
    clientLibrary: { name: string; version: string }
    endpoint: string
    fetchImpl: typeof fetch
    headers: Record<string, string>

    • Convenience wrapper around TiltifyGraphQL.getFactDonations that walks every page and returns the full flat list of donation nodes. Suitable when you actually want every donation; otherwise prefer manual pagination.

      Parameters

      • id: string

        Fact id.

      • pageSize: number = 100

        Donations fetched per page. Defaults to 100.

      Returns Promise<TiltifyDonationNode[]>

      Every donation node across all pages.

      const all = await gql.getAllFactDonations("fact-id", 100);

    • Fetch a cause and one of its fundraising events in a single request. Mirrors the call the Tiltify site makes when rendering an FE landing page (e.g. stjude.tiltify.com/game-warp-2026).

      Parameters

      • params: { causeSlug: string; feSlug: string }

        Cause + FE slug pair.

      Returns Promise<
          {
              cause: TiltifyCauseDetail
              | null;
              fundraisingEvent: TiltifyFundraisingEventSummary | null;
          },
      >

      Both records (each may be null independently).

      const { cause, fundraisingEvent } = await gql.getCauseAndFundraisingEventBySlug({
        causeSlug: "stjude",
        feSlug: "game-warp-2026",
      });

      GraphQL operation get_cause_and_fe_by_slug.

    • Fetch a cause's full profile by slug.

      Parameters

      • slug: string

        Cause slug (e.g. "stjude").

      Returns Promise<TiltifyCauseDetail | null>

      The full cause profile, or null if not found.

      const cause = await gql.getCauseBySlug("stjude");

      GraphQL operation get_cause_by_slug.

    • Top user + team leaderboards for a cause (250 entries each).

      Parameters

      • slug: string

        Cause slug.

      Returns Promise<
          | {
              id: string;
              teamLeaderboard: TiltifyLeaderboard
              | null;
              userLeaderboard: TiltifyLeaderboard | null;
          }
          | null,
      >

      Leaderboards, or null if the cause does not exist.

      const lb = await gql.getCauseLeaderboards("stjude");

      GraphQL operation get_cause_leaderboards.

    • Resolve a tiltify.com/<vanity>/<slug> URL pair to its fact id, template, and usage type. Use this when you only have a slug and need to look up the underlying public id (e.g. for the WebSocket or REST APIs).

      vanity should be the path segment without any leading @ or +. slug is optional — leave it out for a top-level vanity URL.

      Tiltify does not resolve an unknown pair to null — it replies HTTP 200 with {"errors":[{"message":"404"}]}. That not-found case is caught here and normalized to null so the documented contract holds. Any other failure (outage, malformed response, rate limit) still throws, so callers can tell "no such fact" apart from "upstream is broken."

      Parameters

      • params: { slug?: string; vanity: string }

        The vanity and optional slug portions of the URL.

      Returns Promise<TiltifyFactVanitySlug | null>

      The resolved fact pointer, or null if no match.

      On any upstream failure other than not-found.

      const fact = await gql.getFactByVanityAndSlug({
        vanity: "ryantrahan",
        slug: "50states",
      });

      GraphQL operation get_fact_by_vanity_and_slug.

    • Cursor-paginated donations for a fact, ordered ascending by id. Returns the raw GraphQL connection so callers can drive their own pagination using pageInfo.endCursor.

      Parameters

      Returns Promise<TiltifyDonationConnection | null>

      The full donation connection, or null if the fact does not exist.

      const page1 = await gql.getFactDonations({ id: "fact-id", limit: 50 });
      const page2 = await gql.getFactDonations({
        id: "fact-id",
        limit: 50,
        cursor: page1?.pageInfo.endCursor,
      });

      GraphQL operation get_fact_donations_by_id_asc.

    • Donor / user / team leaderboards for any fact (campaign, FE, cause).

      Parameters

      Returns Promise<
          | {
              donorLeaderboard: TiltifyLeaderboard
              | null;
              id: string;
              teamLeaderboard: TiltifyLeaderboard | null;
              userLeaderboard: TiltifyLeaderboard | null;
          }
          | null,
      >

      Three leaderboards, or null if the fact does not exist.

      const lbs = await gql.getFactLeaderboards({ id: "fact-id", limit: 25 });

      GraphQL operation get_default_template_fact_leaderboards.

    • Milestones for a fact (fundraising event, campaign, or cause).

      Wraps the same get_default_template_fact GraphQL operation the tiltify.com FE/campaign landing pages send. That operation returns every panel the marketing template renders (milestones, polls, rewards, sponsors, template config, impact points, fitness data, …) because Tiltify's GraphQL gateway enforces a server-side query-text whitelist — we cannot ship a slimmed-down variant. The wrapper discards everything except the milestones array so callers who only need milestone thresholds don't have to project the payload themselves.

      If you need the full payload (polls, rewards, template panels, impact points, …) send GET_DEFAULT_TEMPLATE_FACT_QUERY yourself via TiltifyGraphQL.query.

      Returns null when the fact does not exist, or an empty array when the fact exists but has no milestones configured. This mirrors the null vs [] split every other fact-scoped helper uses. As with TiltifyGraphQL.getFactByVanityAndSlug, an unknown id comes back from Tiltify as an HTTP 200 carrying a 404 GraphQL error rather than a null resolve, so that case is normalized to null here; every other failure still throws.

      Parameters

      Returns Promise<TiltifyMilestone[] | null>

      The ordered milestones list, or null if the fact is missing.

      On any upstream failure other than not-found.

      const client = new TiltifyGraphQL();

      // 1. Resolve the FE fact id from its landing-page URL.
      const fact = await client.getFactByVanityAndSlug({
        vanity: "stjude",
        slug: "relay-for-st-jude-2026",
      });

      // 2. Fetch the milestones for that fact.
      const milestones = await client.getFactMilestones(fact!.id);
      milestones?.filter((m) => m.active); // "next unhit" milestones

      GraphQL operation get_default_template_fact.

    • All badge groups, with earned flagged for the given user.

      Parameters

      • userId: string

        Tiltify user id.

      Returns Promise<TiltifyBadgeGroup[]>

      Every badge group with per-badge earned/unearned status.

      const groups = await gql.getUserBadges("user-id");

      GraphQL operation get_user_badges.

    • Fetch a full user profile by slug. Returns null when the user does not exist.

      Defaults the return type to the TiltifyUser GraphQL profile shape — byte-compatible with the legacy @playlive/tiltify-tools/user-search TiltifyUser export, so consumers migrating off that package can drop the import specifier in place. Pass a custom TUser only if you've shaped a richer/narrower selection set by overriding the GraphQL operation upstream.

      Type Parameters

      Parameters

      • slug: string

        Tiltify user slug (e.g. "fauxretro").

      Returns Promise<TUser | null>

      The fully hydrated user, or null if not found.

      // Default — typed against the canonical TiltifyUser profile shape.
      const user = await gql.getUserBySlug("fauxretro");
      user?.publishedCampaigns.edges[0]?.node.publicId;

      // Narrowed — swap in your own slim type when you've overridden the query.
      const slim = await gql.getUserBySlug<{ id: string; slug: string }>("fauxretro");

      GraphQL operation get_user_by_slug.

    • Low-level helper: POSTs a GraphQL request and returns the parsed data. Throws on non-2xx HTTP responses or when the body contains errors.

      Every failure mode throws a TiltifyGraphQLError, which carries the raw errors[], the HTTP status (when the failure was HTTP-level), and an isNotFound flag. That flag matters because Tiltify signals a missing resource as HTTP 200 with {"errors":[{"message":"404"}]} rather than a 404 status, so callers cannot classify it from the response status alone.

      Type Parameters

      • TData
      • TVars extends Record<string, unknown> = Record<string, never>

      Parameters

      • operationName: string

        GraphQL operation name (e.g. get_user_by_slug).

      • query: string

        The full GraphQL query string.

      • Optionalvariables: TVars

        Optional variables map for the operation.

      Returns Promise<TData>

      The unwrapped data field from the GraphQL response.

      On any HTTP or GraphQL-level failure.

      const data = await gql.query<{ ping: string }>("ping", "query ping { ping }");

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods