@stackedapp/types 0.26.0

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Re-export all public types
+__exportStar(require("./stacked_offer"), exports);
+__exportStar(require("./stacked_reward"), exports);
+__exportStar(require("./stacked_snapshot"), exports);
+__exportStar(require("./stacked_user"), exports);
+//# sourceMappingURL=index.js.map

package/dist/stacked-types.d.ts

@@ -0,0 +1,788 @@
+interface Stringable {
+    toString(): string;
+}
+type IEnv = 'dev' | 'preview' | 'staging' | 'production' | 'sandbox' | 'local';
+
+/**
+ * TypeScript interface for dynamicGroupSchema
+ */
+type DynamicConditionOperator = '==' | '!=' | '>' | '>=' | '<' | '<=' | 'has' | 'not_has';
+interface IDynamicCondition {
+    key: string;
+    compareTo: string | number | boolean;
+    operator: DynamicConditionOperator;
+    /** If you only want to update this tracker key every X hrs (like once per day), set here */
+    intervalHr?: number;
+}
+/**
+ * links[i] is the link between conditions[i] and conditions[i+1]. Can be 'AND', 'OR', or 'AND NOT'.
+ */
+type DynamicConditionLink = 'AND' | 'OR' | 'AND NOT';
+interface IDynamicGroup {
+    conditions: Array<IDynamicCondition>;
+    links?: Array<DynamicConditionLink>;
+    /** Display template using {keyName} syntax for referenced dynamic keys */
+    template?: string;
+}
+interface IBaseCondition {
+    /** how many days worth of consecutive logins are required to surface? Or complete this? If checking completion conditions, we need to subtract
+     * this number from IPlayerOffer.completionTrackers.currentLoginStreak to see how many consecutive logins the player has had since surfacing this offer.
+     */
+    loginStreak?: number;
+    levels?: Record<string, {
+        /** public facing display name */
+        name: string;
+        /** min level required */
+        min?: number;
+        /** max level for offer */
+        max?: number;
+    }>;
+    stakedTokens?: Record<string, {
+        /** public facing display name */
+        name: string;
+        /** min amount of tokens that need to be staked? */
+        min?: number;
+    }>;
+    /** if the condition revolves around having a specific amount of currency or currencies. Key is the currencyId
+     * and the value is the min or max amount of that currency the player must have to be eligible for this offer
+     */
+    currencies?: Record<string, {
+        /** public facing display name */
+        name: string;
+        /** if the player has this currency, how much do they need to have? */
+        min?: number;
+        /** if the player has this currency, how much do they need to have? */
+        max?: number;
+        /** required deposits required for this currency */
+        in?: number;
+        /** required withdrawals required for this currency */
+        out?: number;
+    }>;
+    /** for high-rep kind, how much rep does a player need to qualify? */
+    minTrustScore?: number;
+    maxTrustScore?: number;
+    /** number of days that the player has logged in-game. Not the absolute amount of time playing the game. But number of days they have logged in for.
+     * Can obtain this on a DAILY join_room player metric if it is set up.
+     */
+    minDaysInGame?: number;
+    /** achievements that this player has */
+    achievements?: Record<string, {
+        name: string;
+        minCount?: number;
+    }>;
+    memberships?: Record<string, {
+        /** public facing display name */
+        name: string;
+        /** if the player has this currency, how much do they need to have? */
+        minCount?: number;
+        /** if the player has this currency, how much do they need to have? */
+        maxCount?: number;
+        /** how long does a player have to have this membership? */
+        minMs?: number;
+        /** max duration a player can have this membership for */
+        maxMs?: number;
+    }>;
+    /** player must have completed these quests for this offer to surface */
+    quests?: Record<string, {
+        /** public facing display name */
+        name: string;
+        /** if a min number of quest completions is required */
+        completions?: number;
+    }>;
+    /**
+     * For player snapshot entities that are linked to other player snap entities,
+     * what are the min and max number of links of a specific link kind?
+     * Keys are link kinds (e.g., "pet", "guild", "npc", etc.)
+     */
+    links?: Record<string, {
+        /** minimum number of links of this type required */
+        min?: number;
+        /** maximum number of links of this type allowed */
+        max?: number;
+    }>;
+    /** dynamic field conditions */
+    dynamic?: IDynamicGroup;
+    /** Auth platform identifiers condition */
+    identifiers?: {
+        /** List of auth platforms to check (e.g., 'tiktok', 'google', 'email') */
+        platforms: string[];
+        /** 'AND' = player must have ALL platforms, 'OR' = player must have ANY platform */
+        behaviour: 'AND' | 'OR';
+    };
+    /**
+     * On-chain token balance conditions - check wallet balances across specified contracts/networks.
+     * Balances are summed across all specified contracts and all player wallets.
+     */
+    tokenBalances?: Array<{
+        /** Display name for this condition (e.g., "PIXEL Token") */
+        name: string;
+        /** List of contract+network pairs to check. Balances summed across all pairs. */
+        contracts: Array<{
+            /** Token contract address (lowercase) */
+            contractAddress: string;
+            /** Network identifier (e.g., 'ronin-mainnet', 'ethereum-mainnet') */
+            network: string;
+        }>;
+        /** Minimum total balance required */
+        min?: number;
+        /** Maximum total balance allowed */
+        max?: number;
+    }>;
+}
+
+/** conditions that must be met for an already surfaced offer to be claimable */
+interface ICompletionCondition extends IBaseCondition {
+    /** itemId that must be bought to complete */
+    buyItem?: {
+        id: string;
+        name: string;
+        /** amount of item bought or currency spent/deposited to fufil condition */
+        amount?: number;
+    };
+    /** currencyId that must be spent to complete */
+    spendCurrency?: {
+        id: string;
+        name: string;
+        /** amount of item bought or currency spent/deposited to fufil condition */
+        amount?: number;
+    };
+    /** currencyId that must be deposited to complete */
+    depositCurrency?: {
+        id: string;
+        name: string;
+        /** amount of item bought or currency spent/deposited to fufil condition */
+        amount?: number;
+    };
+    /** social media content condition - player must attach content meeting requirements */
+    social?: {
+        /** 'attach' (default) = user attaches single content, 'accumulate' = auto-sum all matching content */
+        mode?: 'attach' | 'accumulate';
+        /** platforms accepted (OR logic) - e.g., ['tiktok', 'instagram', 'youtube'] */
+        platforms: string[];
+        /** words that must ALL appear in video title or description (case-insensitive). Hashtags must match exactly including # */
+        requiredWords: string[];
+        /** minimum view count required on the video (0 = no requirement) */
+        minViews: number;
+        /** minimum like count required on the video (0 = no requirement) */
+        minLikes: number;
+        /** minimum comment count required on the video (0 = no requirement) */
+        minComments: number;
+        /** content must be posted after this timestamp in milliseconds (defaults to time of offer creation) */
+        postedAfterMs: number;
+    };
+    login?: boolean;
+    /** for contexts that require completion conditions. We have a name field so that we can display a user-friendly name
+     * for the completion condition when it is rendered to the player. */
+    context?: {
+        id: string;
+        name: string;
+    };
+    /**
+     * Linked completions - wait for N linked entities to complete their offers
+     */
+    linkedCompletions?: {
+        /** Number of linked entity completions required */
+        min: number;
+    };
+    /**
+     * Dynamic field tracker - tracks changes to dynamic fields AFTER offer surfacing.
+     * Unlike the base `dynamic` condition which checks snapshot totals,
+     * this tracks per-offer values since surfacing.
+     */
+    dynamicTracker?: IDynamicGroup;
+    /**
+     * Contract interaction tracker - tracks blockchain events for currencies, NFTs, and custom events.
+     * Keyed by condition ID for multiple trackers.
+     */
+    contractInteractions?: Record<string, {
+        /** Display name for this condition (e.g., "Spend PIXEL", "Earn NFT") */
+        name: string;
+        /**
+         * Event type to track:
+         * - 'spend': Currency transferred OUT (onchain_currency_tx kind=spend)
+         * - 'earn': Currency transferred IN (onchain_currency_tx kind=earn)
+         * - 'lose': NFT transferred OUT (onchain_item_tx kind=lose)
+         * - 'gain': NFT transferred IN (onchain_item_tx kind=gain)
+         * - 'onchain_X': Custom event (e.g., 'onchain_staked')
+         */
+        event: 'spend' | 'earn' | 'lose' | 'gain' | `onchain_${string}`;
+        /** List of contract+network pairs to track. Events from any of these count. */
+        contracts: Array<{
+            /** Contract address (lowercase) */
+            contractAddress: string;
+            /** Network identifier (e.g., 'ronin-mainnet', 'ethereum-mainnet') */
+            network: string;
+        }>;
+        /** Optional: Only count transfers TO these addresses (for spend/lose). Empty = all destinations. */
+        destinations?: string[];
+        /** Optional: Only count transfers FROM these addresses (for earn/gain). Empty = all sources. */
+        sources?: string[];
+        /**
+         * Target amount/count:
+         * - For currencies (spend/earn): token amount
+         * - For NFTs (gain/lose): NFT count
+         * - For custom events: event occurrence count
+         */
+        amount: number;
+    }>;
+}
+interface ICompletionDynamicTracker {
+    value: string | number | boolean;
+    lastUpdated?: number;
+}
+/** tracking the player's status for completing the conditions to claim the offer, if
+ * required.
+ */
+interface ICompletionTrackers {
+    /** how many counts of the required item has been bought. itemId and amount required defined in completionConditions */
+    buyItem?: number;
+    /** how many counts of the required currency has been spent. currencyId and amount required defined in completionConditions */
+    spendCurrency?: number;
+    /** how many counts of the required currency has been deposited. currencyId and amount required defined in completionConditions */
+    depositCurrency?: number;
+    /** the number of days that have been consecutively logged in at the time of surfacing this offer */
+    currentLoginStreak?: number;
+    /** tracks attached social media content and cached validation state */
+    social?: ISocialTrackerAttach | ISocialTrackerAccumulate;
+    /** completed context for this player */
+    context?: string;
+    /**
+     * Count of linked entities that have completed their offers.
+     * For example a referrer refers 5 other referees that have all
+     * completed the referral criteria. this would then be a value of 5.
+     */
+    linkedCompletions?: number;
+    /**
+     * Tracked dynamic field values per key.
+     * Key = dynamic field key, Value = tracked value since offer surfaced
+     */
+    dynamicTracker?: Record<string, ICompletionDynamicTracker>;
+    /**
+     * Tracked contract interaction values per condition ID.
+     * Key = condition ID, Value = accumulated amount/count since offer surfaced
+     * - For spend/earn: token amount
+     * - For gain/lose: NFT count
+     * - For custom onchain events: event occurrence count
+     */
+    contractInteractions?: Record<string, number>;
+}
+/** Social tracker for attach mode - user manually attaches a single piece of content */
+interface ISocialTrackerAttach {
+    /** platform name - tiktok, instagram, or youtube */
+    platform: string;
+    /** video ID on the platform */
+    videoId: string;
+    /** platform specific user ID */
+    userId: string;
+    /** cached video title for display */
+    title?: string;
+    /** cached view count */
+    views: number;
+    /** cached like count */
+    likes?: number;
+    /** cached comment count */
+    comments?: number;
+    /** timestamp of last validation check (for 5-minute cache) */
+    lastChecked: Date;
+}
+/** Social tracker for accumulate mode - auto-sum all matching content */
+interface ISocialTrackerAccumulate {
+    /** sum of view counts across all matching content */
+    views: number;
+    /** sum of like counts across all matching content */
+    likes?: number;
+    /** sum of comment counts across all matching content */
+    comments?: number;
+    /** timestamp of last validation check (for 5-minute cache) */
+    lastChecked: Date;
+    /** number of matching content items */
+    matchCount: number;
+}
+
+interface ISurfacingCondition extends IBaseCondition {
+    /** number of days that the player has logged in-game. Not the absolute amount of time playing the game. But number of days they have logged in for.
+     * Can obtain this on a DAILY join_room player metric if it is set up.
+     */
+    maxDaysInGame?: number;
+    /** player must have all tags specified to be eligible */
+    andTags?: Array<string>;
+    /** player can have any of these tags to be eligible */
+    orTags?: Array<string>;
+    /** player cannot have any of these tags */
+    notTags?: Array<string>;
+    /** minimum signup date (timestamp) - player must have signed up after this date */
+    minDateSignedUp?: number;
+    /** maximum signup date (timestamp) - player must have signed up before this date */
+    maxDateSignedUp?: number;
+    /** player must have completed ALL of these offers (AND logic) - array of offer IDs */
+    completedOffers?: Array<string>;
+    /** surfacing contexts */
+    contexts?: Array<string>;
+    /** if true, offer can only be surfaced programmatically (e.g., via spawnLinkedOffer) - never through normal auto-surfacing */
+    programmatic?: boolean;
+    /** entity types that this offer can surface to - undefined or empty means only regular players. */
+    targetEntityTypes?: string[];
+    /** List of allowed country codes (whitelist mode) */
+    allowedCountries?: Array<string>;
+    /** List of restricted country codes (blacklist mode) - mutually exclusive with allowedCountries */
+    restrictedCountries?: Array<string>;
+    /** List of blocked network types - VPN/TOR/PROXY/RELAY */
+    networkRestrictions?: Array<'vpn' | 'tor' | 'proxy' | 'relay'>;
+    /** Check if any linked entity (by kind) has a specific offer in surfaced/viewed status. */
+    linkedEntityOffers?: {
+        /** The entityLink kind to filter (e.g., "parent", "guild", "pet") */
+        kind?: string;
+        /** The offer_id to check for on linked entities */
+        offer_id?: string;
+        conditions?: ISurfacingCondition;
+    };
+}
+
+interface IReward {
+    /** reward kind */
+    kind: RewardKind;
+    /** if the trigger is type daily-login, which day is this reward for? */
+    /** reward id for rewards of kind item, coins, exp or loyalty currency */
+    rewardId?: string;
+    /** amount of reward to give. If kind is discount, then this refers to the discount amount, as a fraction */
+    amount: number;
+    /** public facing name for this reward */
+    name: string;
+    /** unique image url for this reward */
+    image?: string;
+}
+type RewardKind = 'item' | 'coins' | 'exp' | 'trust_points' | 'loyalty_currency' | 'discount';
+
+/** onSurface and onComplete hooks for offers. Should support:
+ * - Spawning linked offers for referral/referee type offers
+ * - Creating cross-game offers
+ * - Surfacing offers to other linked player snapshots
+ *
+ * When an offer is SURFACED to a player, we are able to:
+ * - surface a linked offer in same game to self
+ * - surface a linked offer in same game to other players
+ * - surface a linked offer in different game to other players
+ *
+ * When an offer is COMPLETED by a player, we are able to:
+ * - increment linked tracker of any player offer
+ * - surface a linked offer in same game to self
+ * - surface a linked offer in same game to other players
+ * - surface a linked offer in different game to other players
+ */
+interface IOfferHookEvent {
+    _id?: undefined | false | null;
+    kind: 'spawn_linked_offer' | 'increment_linked_tracker' | 'increment_completed_siblings' | 'attach_player_entity_link_offers';
+    /** player snapshot entity kind that we are spawning the linked offer for */
+    target?: 'self' | string;
+}
+type OfferListenerEvent = 'claim_offer';
+interface IOfferListener extends IOfferHookEvent {
+    event: OfferListenerEvent;
+}
+interface IOffer {
+    _id: Stringable;
+    /** for grouping offers together if they are assocaited with each othert for easy rendering in front-end */
+    groupId?: string;
+    name: string;
+    /** how high of a priority is this offer in comparison to other offers? 1 is highest priority */
+    priority?: number;
+    description: string;
+    createdAt?: Date;
+    /** notes about this offer */
+    notes?: string;
+    /** if this should be an offer that gets surfaced in real time */
+    realTime?: string;
+    /** if this offer is tied to other offers for a/b testing, this is the ID that ties
+     * all of the offers together
+     */
+    campaign?: string;
+    image?: string;
+    /** game that this offer corresponds to */
+    gameId: string;
+    /** start date of surfacing this offer to players */
+    startDate?: Date;
+    /** end date of surfacing this offer to players */
+    endDate?: Date;
+    /** if fully archived, the offer will be deleted from memory and not be surfaced anymore to ANYONE. Current players with the offer will no longer see it */
+    archived?: boolean;
+    /** is this offer disabled right now? */
+    disabled?: boolean;
+    /** labels for UI stuff */
+    labels?: Array<string>;
+    /** how long after completing this offer can a player get the same offer again? If undefined, this offer only shows up once EVER for the player */
+    cooldownMs?: number;
+    /** how long after a player receives this offer is it available for, before ing? */
+    expiryMs?: number;
+    /** @description DO NOT USE! */
+    surfacingContexts?: string[];
+    /** conditions that all must be fulfilled if this offer is to be surfaced to a player */
+    surfacingConditions: ISurfacingCondition;
+    /** triggers that allow this offer to be claimable. Leave empty if merely surfacing the offer should allow claiming. */
+    completionConditions?: ICompletionCondition;
+    /**
+     * Conditions for transitioning from 'completed' to 'claimable' status.
+     * If absent, offers go directly to claimable when completionConditions are met.
+     */
+    claimableConditions?: {
+        /** number of sibling offers that must be completed to make this offer claimable (-1 means all siblings) */
+        siblingCompletions?: number;
+    };
+    /** what does completing this offer reward the player? */
+    rewards: Array<IReward>;
+    /** if you can claim rewards multiple times, what is the max claim count you can claim? */
+    maxClaimCount?: number;
+    /**
+     * Linked offer configuration - specifies which offer to spawn when this offer surfaces or completes
+     */
+    linkedOffer?: {
+        /** Specific offer _id to spawn */
+        _id?: Stringable;
+        /** OR use campaign for A/B test selection via GrowthBook.
+         *
+         * !!!THIS IS NOT SUPPORTED FOR CROSS-GAME OFFERS!!!
+         */
+        campaign?: string;
+    };
+    /**
+     * Actions to perform when this offer is surfaced to a player/entity
+     */
+    onSurface?: Array<IOfferHookEvent>;
+    /**
+     * Actions to perform when ANY instance of this offer is completed
+     * Gets copied to PlayerOffer and populated with specific IDs
+     */
+    onComplete?: Array<IOfferHookEvent>;
+    /**  */
+    eventListeners?: Array<IOfferListener>;
+    invitedGameId?: string;
+}
+
+type PlayerOfferStatus = 'surfaced' | 'viewed' | 'completed' | 'claimable' | 'claimed' | 'expired';
+interface IPlayerOfferTrackers {
+    /********************** These are not really completion trackers, but just regular trackers **********************/
+    /** player snapshot _id of the person who surfaced this offer */
+    surfacer_id?: Stringable;
+    /** playerId of the person who surfaced this player offer */
+    surfacerPlayerId?: string;
+    /** gameId of the game who surfaced this player offer */
+    surfacerGameId?: string;
+    /** the referral code used to activate the .linkedOffer from the offer. */
+    referralCode?: string;
+    /** number of linked player offers spawned off this one. */
+    linkedCount?: number;
+    /** if this playerOffer was created due to someone else's offer hook event, what was their player offer _id? */
+    linkedPlayerOffer_ids?: Array<Stringable>;
+    /**
+     * IDs of sibling PlayerOffers created together (e.g., both parents from a pet offer).
+     * Used to check if all siblings completed before any can claim.
+     * If any sibling expires, all siblings should expire (strict co-op).
+     */
+    siblingPlayerOffer_ids?: Array<Stringable>;
+    /**
+     * Tracks how many times a linked offer has been surfaced (for cross-game offers)
+     * Used to prevent duplicate surfacing when games are linked/unlinked/relinked
+     */
+    surfacedCount?: number;
+    claimedCount?: number;
+}
+interface IPlayerOffer {
+    _id: Stringable;
+    /** starts at 1. multiples of the cooldown timeframe if there is a cooldown. there is a unique index on this and
+     * it ensures that we do not get multiple offers created for the same offer in the same cooldown timeframe if someone
+     * tries to abuse and slam the fetchPlayerOffers endpoint
+     */
+    cooldownTimeframeMultiple?: number;
+    /** offer id */
+    offer_id: Stringable | IOffer;
+    /** is this an offer that should be surfaced AND PUSHED in real-time to a player? */
+    realTime?: boolean;
+    claimedAt?: Date;
+    rewards: Array<IReward>;
+    /** tracking the player's status for completing the conditions to claim the offer, if
+     * required.
+     */
+    completionTrackers?: ICompletionTrackers;
+    trackers?: IPlayerOfferTrackers;
+    /**
+     * Trackers for claimableConditions (completed → claimable transition).
+     */
+    claimableTrackers?: {
+        /** Counter incremented when a sibling offer completes */
+        siblingCompletions?: number;
+    };
+    /** status of the offer
+     * - surfaced: offer is now surfaced to the player, but not viewed by the player yet.
+     * - viewed: offer has been viewed by the player, but not yet completed. The expiration time only starts when the player views the offer
+     * - completed: individual completionConditions met, waiting for claimableConditions (e.g., all siblings must complete)
+     * - claimable: offer has been completed and is now claimable by the player
+     * - claimed: offer has been completed and the player has claimed the rewards.
+     * - expired: offer has expired and is no longer available to the player
+     */
+    status: PlayerOfferStatus;
+    /** player _id */
+    playerId: string;
+    /** game _id */
+    gameId: string;
+    /** created at date */
+    createdAt: Date;
+    /** expiry date */
+    expiresAt?: Date;
+    /**
+     * Actions to perform when this PlayerOffer is completed
+     */
+    onComplete?: Array<IOfferHookEvent>;
+}
+
+type CoinSyncStatusType = "pending" | "success" | "error" | "exclusive" | "synced" | null;
+interface IBlockchainSyncStatus {
+    ts: number | null;
+    status: CoinSyncStatusType;
+    waiting?: boolean;
+    error?: string;
+}
+
+interface AppConnection {
+    gameId: string;
+    playerId: string;
+    linkedAt: Date;
+}
+type Restriction = {
+    kind?: 'block' | 'restrict';
+    start?: number;
+    until?: number;
+    eventCount: number;
+    message?: string;
+};
+interface IUser {
+    _id: Stringable;
+    deleted?: boolean;
+    authId: string;
+    lastLoggedIn?: number;
+    appConnections?: Array<AppConnection>;
+    notifications?: {
+        /** last push notification sent */
+        lastPushed?: number;
+        /** last push notification that was deep linked into a specific offer or campaign */
+        lastPushedOffer?: number;
+        /** last push generic notification to come back into the app */
+        lastPushedGeneric?: number;
+    };
+    cryptoWallets?: Array<{
+        address: string;
+        createdAt: number;
+    }>;
+    rewardWallets?: Array<{
+        address: string;
+        createdAt: number;
+        networks: Array<string>;
+    }>;
+    providers?: Array<{
+        provider: string;
+        accessToken: string;
+        refreshToken?: string;
+        expiresAt?: Date;
+        refreshTokenExpiresAt?: Date;
+        scope?: string;
+        tokenType?: string;
+        providerUserId?: string;
+        updatedAt: Date;
+        displayName?: string;
+        username?: string;
+    }>;
+    restriction?: Restriction;
+}
+
+interface IPlayerSnapshot {
+    _id: string;
+    gameId: string;
+    playerId: string;
+    /** when this was last linked to a unified user */
+    unifiedUserLinkedAt?: number;
+    /** when this was last unlinked to a unified user */
+    unifiedUserUnlinkedAt?: number;
+    /** player that referred this player to this game */
+    referredById?: string;
+    username?: string;
+    snapshotLastUpdated: number;
+    offersLastChecked?: number;
+    daysInGame: number;
+    loginStreak: number;
+    daysInGameLastUpdated: number;
+    /** timestamp when player first signed up */
+    dateSignedUp?: number;
+    /** dynamic key value pairs that external apps can set to anything */
+    dynamic?: Record<string, string | number | boolean>;
+    /** staked tokens data for this player */
+    stakedTokens?: Record<
+    /** the key is the token name. Eg. PIXEL or RON */
+    string, {
+        balance?: number;
+        totalClaimed?: number;
+        totalStaked?: number;
+        lastStake?: number;
+        lastUnstake?: number;
+    }>;
+    currencies?: Record<string, {
+        balance?: number;
+        in?: number;
+        out?: number;
+        lastUpdated?: number;
+    }>;
+    levels?: Record<string, {
+        level?: number;
+        lastUpdated?: number;
+    }>;
+    quests?: Record<string, {
+        completions?: number;
+        lastUpdated?: number;
+    }>;
+    trustScore?: number;
+    trustLastUpdated?: number;
+    achievements?: Record<string, {
+        count?: number;
+        lastUpdated: number;
+    }>;
+    memberships?: Record<string, {
+        count?: number;
+        expiresAt?: number;
+        lastUpdated?: number;
+    }>;
+    /** auth identifiers. like social tiktok or email or sms or whatever */
+    identifiers?: Array<{
+        /** id */
+        identifier: string;
+        /** sms/email/tiktok etc */
+        platform: string;
+        lastUpdated: number;
+    }>;
+    cryptoWallets?: Array<{
+        address: string;
+        lastUpdated?: number;
+    }>;
+    tags?: Array<string>;
+    tagsLastUpdated?: number;
+    entityKind?: string;
+    /**
+     * Links to other entities (players, pets, guilds, etc.)
+     */
+    entityLinks?: Array<{
+        /** if undefined, it means same game */
+        gameId?: string;
+        playerId: string;
+        kind?: string;
+    }>;
+    /**
+     * collection of information about IP address player connected from
+     */
+    ip?: IPlayerIpInfo;
+}
+interface IPlayerDataCurrency {
+    /**
+     * balance held
+     */
+    balance: number;
+    /**
+     * total amount deposited
+     */
+    in?: number;
+    /**
+     * total amount withdrawn
+     */
+    out?: number;
+    /**
+     * last updated timestamp
+     * if not present, means never updated
+     */
+    lastUpdated?: number;
+}
+interface IPlayerData {
+    _id?: Stringable;
+    gameId: string;
+    playerId: string;
+    currencies?: Record<string, IPlayerDataCurrency>;
+    blockchainSync?: Record<string, IBlockchainSyncStatus>;
+    restriction?: Restriction;
+}
+interface IPlayerIpInfo {
+    lastUpdated: Date;
+    ipAddress: string;
+    vpn?: boolean;
+    proxy?: boolean;
+    tor?: boolean;
+    relay?: boolean;
+    timeZone: string;
+    regionCode?: string;
+    countryCode?: string;
+    continentCode?: string;
+}
+
+/** this is the Stacked platforms' copy of a user/entity's snapshot for the current app/game */
+type StackedSnapshot = Pick<IPlayerSnapshot, '_id' | 'gameId' | 'playerId' | 'unifiedUserLinkedAt' | 'unifiedUserUnlinkedAt' | 'referredById' | 'username' | 'snapshotLastUpdated' | 'offersLastChecked' | 'daysInGame' | 'loginStreak' | 'daysInGameLastUpdated' | 'dateSignedUp' | 'dynamic' | 'stakedTokens' | 'currencies' | 'levels' | 'quests' | 'trustScore' | 'trustLastUpdated' | 'achievements' | 'memberships' | 'entityKind' | 'entityLinks'>;
+/** represents a stacked snapshot's data within a specific app/game. This is scoped to the app/game! */
+type StackedSnapshotData = Pick<IPlayerData, 'gameId' | 'playerId' | 'currencies'>;
+
+type StackedCompletionConditions = ICompletionCondition;
+/** Stripped sibling offer data for client rendering */
+interface StackedSnapshotProgress {
+    status: UserOfferStatus;
+    completionTrackers?: ICompletionTrackers;
+    completionConditions?: ICompletionCondition;
+    snapshot?: StackedSnapshot;
+}
+/** offer fields that define this offer's properties */
+interface StackedBaseOffer extends Pick<IOffer, OfferPickFields> {
+    /** Siblings */
+    siblings?: StackedSnapshotProgress[];
+    /** Progress data for linked entity's offer (e.g., pet's progress on their task) */
+    linked?: StackedSnapshotProgress[];
+    completionConditions: StackedCompletionConditions;
+}
+type OfferPickFields = 'groupId' | 'name' | 'description' | 'image' | 'gameId' | 'archived' | 'disabled' | 'labels' | 'claimableConditions' | 'rewards' | 'maxClaimCount';
+/** user-specific offer fields for this specific user's offer progress */
+interface StackedUserOffer extends Pick<IPlayerOffer, UserOfferPickFields> {
+}
+type UserOfferPickFields = 'claimedAt' | 'rewards' | 'completionTrackers' | 'trackers' | 'claimableTrackers' | 'status' | 'playerId' | 'gameId' | 'createdAt' | 'expiresAt' | 'onComplete';
+type UserOfferStatus = PlayerOfferStatus;
+/** complete offer object that defines the offer and user's progress within the offer. The
+ * rewards field is taken from the UserOffer rather than the BaseOffer
+ */
+type StackedOffer = StackedBaseOffer & StackedUserOffer & {
+    /** offer id */
+    offerId: string;
+    /** user offer id */
+    instanceId: string;
+};
+
+type StackedRewardKind = RewardKind;
+interface StackedReward extends IReward {
+    image?: string;
+}
+
+/** represents a stacked consumer from the web/mobile app */
+type StackedBaseUser = Pick<IUser, 'appConnections' | 'providers'>;
+/** extra data populated into a stacked web/mobile app user */
+interface StackedBaseUserExtra {
+    cryptoWallets?: Array<{
+        address: string;
+        balances: Record<string, number>;
+    }>;
+}
+type StackedUser = StackedBaseUser & StackedBaseUserExtra & {
+    apps: {
+        [appId: string]: StackedSnapshotData;
+    };
+};
+/** @deprecated - old way of getting a specific game player's currencies in stacked */
+type IClientPlayerData = StackedSnapshotData;
+type StackedUserResponse = {
+    /** @deprecated use stacked instead */
+    data?: IClientPlayerData | null;
+    /** this is the current user's snapshot within this app/game */
+    snapshot: StackedSnapshot;
+    /** this current user's stacked web/mobile app profile */
+    user: StackedUser;
+};
+
+type StackedEnv = IEnv;
+
+export type { IClientPlayerData, StackedBaseOffer, StackedBaseUser, StackedBaseUserExtra, StackedCompletionConditions, StackedEnv, StackedOffer, StackedReward, StackedRewardKind, StackedSnapshot, StackedSnapshotData, StackedSnapshotProgress, StackedUser, StackedUserOffer, StackedUserResponse, UserOfferStatus };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stackedapp/types",
+  "version": "0.26.0",
+  "description": "Public types for Stacked platform SDK",
+  "main": "dist/index.js",
+  "types": "dist/stacked-types.d.ts",
+  "files": [
+    "dist/index.js",
+    "dist/stacked-types.d.ts"
+  ],
+  "private": false,
+  "scripts": {
+    "build": "tsc && api-extractor run -l && rollup -c rollup.config.mjs",
+    "build:tsc": "tsc",
+    "build:bundle-types": "rollup -c rollup.config.mjs",
+    "clean": "rimraf dist"
+  },
+  "devDependencies": {
+    "@stackedplatform/types-internal": "*",
+    "@microsoft/api-extractor": "^7.55.2",
+    "typescript": "^5.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC"
+}