cs-float-api

Table of Contents

• Key Features
• Installation
• Quick Start
• API Reference
  • CsFloatClient
  • SchemaFetcher
  • Event Emitter
  • Enums & Error Codes
  • Expression Builder & Parser
    • BuyOrderExpressionBuilder
    • BuyOrderExpressionParser
• Schemas & Interfaces
• Available Types & Payloads
• Event Payloads

This README was generated with the assistance of ChatGPT.

A lightweight, fully typed TypeScript library for working with the CSFloat service. Built on an event-driven model, it lets you subscribe to real-time updates and manage all aspects of your CS:GO account and trade operations with zero boilerplate.

Key Features

• 🎮 Real-Time Data Updates
  Subscribe to strongly-typed events for profile changes, inventory updates, listings, offer history, notifications, and more—no polling required.

• 🔄 Strictly Typed Events & Payloads
  Each API response (UpdateMe, UpdateListings, UpdateInventory, etc.) is exposed as a properly defined interface. Rate limits and errors are emitted as typed events.

• 🤝 Comprehensive Trade Management
  Methods for creating, cancelling, and accepting trade offers; placing and updating buy orders; configuring auto-bidding, maximum bargaining, and stall visibility/away status.

• 📦 Expression Builder & Parser
  Utility classes to construct buy-order expressions programmatically and parse existing expressions back into structured parameters.

• 🌐 Universal Bundles
  Ships pre-built for CommonJS, ESM, and UMD so you can use it in Node.js scripts, modern bundlers, or directly in the browser.

• 📜 Type Declarations & Sourcemaps
  Includes .d.ts files and source maps for seamless IDE autocomplete and easy debugging.

Installation

npm install cs-float-api

Quick Start

import { CsFloatClient } from 'cs-float-api';

// Initialize the client
const client = new CsFloatClient({
  apiKey: process.env.CS_FLOAT_KEY,
  //or
  session: process.env.CS_FLOAT_SESSION,
});

// Listen for profile updates
client.on('api:UpdateMe', (profile) => {
  console.log('Logged in as', profile.username);
});

// Fetch csfloat profile
await client.getMe().catch((res) => {
  console.log(`[Error] GetMe: ${res.message}`);
  return null;
});

Equip your bots, dashboards, and trading tools with a robust, event-driven interface to CSFloat—ditch manual HTTP calls and embrace full TypeScript safety!

API Reference

CsFloatClient

The CsFloatClient exposes methods to interact with the CSFloat API and emit events defined in CsFloatClientEvents.

new CsFloatClient(options: CsFloatApiKeyOptions | CsFloatSessionOptions)

SchemaFetcher

Static methods to load and query the CSFloat API schema information (item definitions, rarities, collections):

import { SchemaFetcher } from 'cs-float-api';

Event Emitter

All server-sent updates are emitted through the standard EventEmitter API:

client.on('api:UpdateInventory', (items) => console.log(items.length));
client.emit('api:UpdateBuyOrders', buyOrdersArray);

Enums & Error Codes

Import CsFloatTransactionType and Rarity from the library to work with constant sets, and check CSFloatErrorCodes for API error messages.

Expression Builder & Parser

CS-Float uses a custom expression syntax for buy orders. The library provides BuyOrderExpressionBuilder and BuyOrderExpressionParser to work with these expressions.

BuyOrderExpressionBuilder

Constructor

new BuyOrderExpressionBuilder(initialExpression?: string)

• initialExpression: Optional raw expression string to parse as the starting AST.

Instance Methods

• addRule(field, operator, value): this
  Add a comparison rule.

  • field: one of BuyOrderField (e.g., 'FloatValue', 'DefIndex', 'Rarity', etc.)
  • operator: field-specific operator (e.g., '==', '>=', 'has')
  • value: constant of the correct type (number, boolean, or string)

• addStickerRule(stickerId, options): this
  Add a sticker requirement.

  • stickerId: numeric sticker identifier
  • options: exactly one of { qty: number } or { slot: number }

• addGroup(condition, callback): this
  Nest a group of rules under an 'and' or 'or' condition.

  • condition: 'and' | 'or'
  • callback: receives a fresh BuyOrderExpressionBuilder to define sub-rules

• buildExpression(): IExpressionGroup
  Returns the internal AST representing all added rules and groups.

• getExpression(): IExpressionGroup
  Alias for buildExpression().

• buildBuyOrder(max_price, quantity): IPlaceBuyOrderBody
  Create the final request payload:

  • Validates that required fields (DefIndex and PaintIndex) are present.
  • Returns { expression: IExpressionGroup; max_price; quantity }.

Static Methods

• BuyOrderExpressionBuilder.parse(raw: string): IExpressionGroup
  Parse a raw expression into an AST, throwing on invalid syntax.

• BuyOrderExpressionBuilder.parseRarity(value: string): Rarity
  Convert a rarity name (e.g., 'Classified') into the Rarity enum value.

BuyOrderExpressionParser

An alias for BuyOrderExpressionBuilder.parse:

const ast = BuyOrderExpressionParser.parse(rawExpression);

Schemas & Interfaces

Below are the core schema and interface definitions provided by the library. Import and reference these to work with raw API responses, request parameters, and AST types.

// Authentication & Client Options
type CsFloatApiKeyOptions = { apiKey: string; endpoint?: string };
type CsFloatSessionOptions = { sessionToken: string; endpoint?: string };

// User Profile
type ICsFloatMeResponse = {
  id: string;
  username: string;
  steamId: string;
  avatarUrl: string;
  balance: number;
  currency: string;
  tradeUrl?: string;
};

// Listings & Inventory
type IListingEntry = {
  listingId: number;
  item: ISchemaItem;
  price: number;
  currency: string;
  quantity: number;
  createdAt: string;
};
type ICsFloatListingsResponse = {
  listings: IListingEntry[];
  total: number;
  page: number;
  pageSize: number;
};
type IInventoryItem = {
  assetId: string;
  marketHashName: string;
  schemaItem: ISchemaItem;
  floatValue?: number;
  paintIndex?: number;
  stickers?: Array<{ stickerId: number; slot: number }>;
};

// Notifications & Offers
type INotificationsResponse = { notifications: Array<{ id: string; message: string; createdAt: string }> };
type IOfferHistory = { timestamp: string; status: string; details?: string };
type IOffersResponse = { offers: ITradeOffer[]; count: number };
type ITradeOffer = {
  offerId: string;
  itemsToGive: IInventoryItem[];
  itemsToReceive: IInventoryItem[];
  status: string;
  createdAt: string;
};
type ITradeOfferResponse = { offers: ITradeOffer[] };

// Buy Orders
type IPlaceBuyOrderBody = { expression: IExpressionGroup; max_price: number; quantity: number };
type IBuyOrder = {
  orderId: string;
  expression: IExpressionGroup;
  maxPrice: number;
  quantity: number;
  filled: number;
  createdAt: string;
};

type IAutoBitsResponse = { enabled: boolean; message: string };
type ICsFloatAccountStandingResponse = { score: number; level: number; status: string };

// Schema Definitions
interface ISchemaItem {
  defIndex: number;
  name: string;
  type: string;
  rarity: Rarity;
  exterior: string;
  marketable: boolean;
}
interface ISchemaCollectionItem { name: string; items: number[]; }
interface ISchemaRarityItem { name: string; value: Rarity }
interface IMarketHashVariant { paintIndex: number; quality: string; statTrak: boolean; souvenir: boolean }

// Request Parameter Interfaces
type IGetListingsParams = { page?: number; pageSize?: number; sortBy?: string };
type IGetInventoryParams = { steamId?: string; tradableOnly?: boolean };
type IGetNotificationsParams = { unreadOnly?: boolean; limit?: number };
type IGetOfferHistoryParams = { limit?: number };
type IGetOffersTimelineParams = { direction?: 'in' | 'out'; limit?: number };

// Expression AST Interfaces
interface IExpressionRule {
  field: BuyOrderField;
  operator: string;
  value: string | number | boolean;
}
interface IExpressionGroup {
  condition: 'and' | 'or';
  rules: Array<IExpressionRule | IExpressionGroup>;
}

// Enums & Constants
enum Rarity { Common = 1, Uncommon, Rare, Mythical, Legendary, Ancient, Extraordinary }
enum BuyOrderField { DefIndex = 'DefIndex', FloatValue = 'FloatValue', Rarity = 'Rarity', PaintIndex = 'PaintIndex' }

Available Types & Payloads

Import these interfaces to use the correct types for event handlers and API responses.

import {
  ICsFloatMeResponse,
  ICsFloatListingsResponse,
  IInventoryItem,
  INotificationsResponse,
  IOfferHistory,
  IOffersResponse,
  IListingEntry,
  ISaleItemParams,
  IBuyOrder,
  ITradeOffer,
  IAutoBitsResponse,
  ICsFloatAccountStandingResponse,
  ITradeOfferResponse
} from 'cs-float-api';

Event Payloads

For more details, explore the source code.

This README was generated with the assistance of ChatGPT.