docs: overhaul docs for 0.9.2

Author: Krablante

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-03-10
+
+### Changed
+
+1. expanded `docs/` from a light task-oriented hub into a fuller package-level documentation set, covering the complete runtime surface across resources, workflows, helper exports, CLI usage, transport behavior, and stability guidance
+
 ## [0.9.1.5] - 2026-03-10
 
 ### Added

README.md

@@ -19,23 +19,26 @@ The project is intentionally conservative about claims. Anything called `impleme
 
 > The goal is simple: be the SDK you reach for first if you want serious CSFloat automation instead of a thin wrapper.
 >
-> Install from npm: [`csfloat-node-sdk@0.9.1.5`](https://www.npmjs.com/package/csfloat-node-sdk)
+> Install from npm: [`csfloat-node-sdk@0.9.2`](https://www.npmjs.com/package/csfloat-node-sdk)
 
 ## Documentation
 
+The docs set now aims to cover the full public runtime surface of the package, not just the quick-start path.
+
 If you want the fastest path through the SDK, start here:
 
 1. [Documentation Hub](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/README.md)
 2. [Getting Started](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/getting-started.md)
-3. [Resources And Workflows](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/resources-and-workflows.md)
-4. [Transport, Errors, And Metadata](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/transport-and-errors.md)
-5. [Examples And Recipes](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/examples-and-recipes.md)
-6. [API Coverage Matrix](https://github.com/Krablante/csfloat-node-sdk/blob/main/API_COVERAGE.md)
-
-Current recommendation:
-
-1. keep documentation GitHub/npm-first while the information architecture is still evolving
-2. only add a separate docs site later, using this same Markdown content as the source of truth
+3. [Resources, Workflows, And Surface Map](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/resources-and-workflows.md)
+4. [Resource Reference](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/resource-reference.md)
+5. [Helpers, Builders, And Constants](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/helpers-and-builders.md)
+6. [Workflows And CLI](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/workflows-and-cli.md)
+7. [Transport, Errors, And Metadata](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/transport-and-errors.md)
+8. [Examples And Recipes](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/examples-and-recipes.md)
+9. [Stability And Coverage](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/stability-and-coverage.md)
+10. [API Coverage Matrix](https://github.com/Krablante/csfloat-node-sdk/blob/main/API_COVERAGE.md)
+
+These Markdown docs ship in the npm tarball as well, so npm users are not forced onto a separate site just to understand the SDK.
 
 ## Why Choose This SDK
 

docs/README.md

@@ -1,51 +1,77 @@
 # Documentation Hub
 
-This SDK already ships a broad surface. The fastest way to make it usable is not
-to make the main README even longer, but to give users a clear map.
+This docs set is meant to cover the full public runtime surface of `csfloat-node-sdk`:
 
-If you are reading this on npm:
+- `CsfloatSdk` resources
+- `sdk.client` and `CsfloatHttpClient`
+- workflow helpers
+- builder/helper/constant exports from the package root
+- CLI commands
+- the stability and coverage notes needed to use the SDK responsibly
 
-1. start with the repository README for the high-level pitch and install snippet
-2. use this `docs/` directory for task-oriented guidance
-3. use `API_COVERAGE.md` when you need endpoint-level truth
+If you are reading this from the published npm package, these files ship in the tarball.
 
-## Start Here
+## Recommended Reading Order
 
-- [Getting Started](./getting-started.md)
-  First install, API key setup, first requests, local verification.
-- [Resources And Workflows](./resources-and-workflows.md)
-  Which SDK surface to use for market reads, account automation, loadouts, and higher-level helpers.
-- [Transport, Errors, And Metadata](./transport-and-errors.md)
-  Retries, pacing, typed errors, and the new opt-in response metadata surface.
-- [Examples And Recipes](./examples-and-recipes.md)
-  Examples, CLI commands, and which script to run for common tasks.
+1. [Getting Started](./getting-started.md)
+   Install, first client, first requests, and where to go next.
+2. [Resources, Workflows, And Surface Map](./resources-and-workflows.md)
+   Which surface to use for each kind of task.
+3. [Resource Reference](./resource-reference.md)
+   The method-level reference for `sdk.meta`, `sdk.account`, `sdk.listings`, and the rest.
+4. [Helpers, Builders, And Constants](./helpers-and-builders.md)
+   Every exported helper module and the constants that shape queries or requests.
+5. [Workflows And CLI](./workflows-and-cli.md)
+   The higher-level orchestration layer plus the published CLI commands.
+6. [Transport, Errors, And Metadata](./transport-and-errors.md)
+   `CsfloatHttpClient`, retries, pacing, metadata responses, and error handling.
+7. [Examples And Recipes](./examples-and-recipes.md)
+   Runnable examples plus copyable snippets for common flows.
+8. [Stability And Coverage](./stability-and-coverage.md)
+   How to interpret implemented vs low-level vs account-gated behavior.
+9. [`API_COVERAGE.md`](../API_COVERAGE.md)
+   Endpoint-level truth for validated and discovered routes.
 
-## How To Read This SDK
+## Choose By Task
 
-Use the SDK in three layers:
+- First request or install help:
+  [Getting Started](./getting-started.md)
+- Which resource or helper to reach for:
+  [Resources, Workflows, And Surface Map](./resources-and-workflows.md)
+- Exact public methods on each resource:
+  [Resource Reference](./resource-reference.md)
+- Exported builders, presets, constants, and pagination helpers:
+  [Helpers, Builders, And Constants](./helpers-and-builders.md)
+- High-level snapshot helpers or CLI usage:
+  [Workflows And CLI](./workflows-and-cli.md)
+- Transport behavior, retries, rate limits, or raw metadata:
+  [Transport, Errors, And Metadata](./transport-and-errors.md)
+- Copyable code for real tasks:
+  [Examples And Recipes](./examples-and-recipes.md)
+- Support confidence, caveats, and route truth:
+  [Stability And Coverage](./stability-and-coverage.md) and [`API_COVERAGE.md`](../API_COVERAGE.md)
 
-1. `CsfloatSdk` resources for normal application code
-2. helpers/builders/workflows when you want less glue code
-3. `sdk.client.*WithMetadata()` when you need low-level response visibility
+## What This Docs Set Covers
 
-## Where Different Kinds Of Truth Live
-
-- Product overview: `README.md`
-- Stable endpoint coverage notes: `API_COVERAGE.md`
-- Release history: `CHANGELOG.md`
-- Task-oriented usage: `docs/*.md`
-- Executable examples: `examples/*.mjs`
-
-## Should You Build A Separate Docs Site?
+- every public runtime entrypoint exported from the package root
+- every SDK resource and workflow method
+- the helper functions and constants that materially affect day-to-day usage
+- the published CLI surface
+- the transport and error model
 
-Not yet, unless you are ready to keep GitHub, npm, and the site in sync.
+The root package also exports a very large TypeScript type surface. These docs call out the important request and response types by area, but the generated `.d.ts` files and your IDE remain the authoritative field-level reference.
 
-The better near-term strategy is:
-
-1. keep GitHub + npm-readable docs as the source of truth
-2. keep docs in Markdown inside the package repository
-3. only later add a Vercel-hosted site that reuses this same content
+## Where Different Kinds Of Truth Live
 
-That way npm users are not forced onto an external site just to understand the
-package, and a future docs site becomes a presentation layer, not a second
-documentation system.
+- Product overview and install snippet:
+  [`README.md`](../README.md)
+- Runtime docs:
+  `docs/*.md`
+- Endpoint-by-endpoint validation and discovery notes:
+  [`API_COVERAGE.md`](../API_COVERAGE.md)
+- Release history:
+  [`CHANGELOG.md`](../CHANGELOG.md)
+- Executable examples:
+  `examples/*.mjs`
+- Tests for supported behavior:
+  `test/*.test.ts`

docs/examples-and-recipes.md

@@ -2,14 +2,16 @@
 
 ## Shipped Examples
 
-These examples are already publishable and included in the npm tarball:
+These examples are published with the package and included in the npm tarball:
 
-- `examples/basic.mjs`
-- `examples/market-public-feeds.mjs`
-- `examples/watchlist-stall-iteration.mjs`
-- `examples/loadout-companion.mjs`
-- `examples/buy-order-expression.mjs`
-- `examples/workflows.mjs`
+| File | Shows |
+|---|---|
+| `examples/basic.mjs` | authenticated `me` + inventory + public stall bootstrap |
+| `examples/market-public-feeds.mjs` | public listings with homepage/public-page presets |
+| `examples/watchlist-stall-iteration.mjs` | authenticated watchlist iteration plus public stall iteration |
+| `examples/loadout-companion.mjs` | recommender token flow plus loadout discover/recommend helpers |
+| `examples/buy-order-expression.mjs` | single-skin expression preview plus similar buy-order lookup |
+| `examples/workflows.mjs` | the higher-level `sdk.workflows` layer end to end |
 
 ## Example Commands
 
@@ -24,13 +26,22 @@ npm run example:workflows
 
 ## CLI Commands
 
+If you are working from source after `npm run build`:
+
 ```bash
 node dist/cli.js help
 node --env-file=.env dist/cli.js feeds
 node --env-file=.env dist/cli.js workspace
 node --env-file=.env dist/cli.js buy-order-similar --def-index 7 --paint-index 72 --stattrak false --souvenir false
 ```
 
+If you are using the published package:
+
+```bash
+npx csfloat-node-sdk help
+npx csfloat-node-sdk feeds --api-key "$CSFLOAT_API_KEY"
+```
+
 ## Recommended Recipe Paths
 
 - Public feed snapshot:
@@ -44,6 +55,136 @@ node --env-file=.env dist/cli.js buy-order-similar --def-index 7 --paint-index 7
 - Higher-level multi-call orchestration:
   `examples/workflows.mjs`
 
+## Common Recipes
+
+Assume `const sdk = new CsfloatSdk({ apiKey: process.env.CSFLOAT_API_KEY! });` unless the snippet shows otherwise.
+
+### Public Market Snapshot
+
+```ts
+import {
+  CsfloatSdk,
+  getHomepageFeedParams,
+  getPublicMarketPageParams,
+} from "csfloat-node-sdk";
+
+const sdk = new CsfloatSdk({ apiKey: process.env.CSFLOAT_API_KEY! });
+
+const [publicPage, topDeals] = await Promise.all([
+  sdk.listings.getListings(getPublicMarketPageParams()),
+  sdk.listings.getListings(getHomepageFeedParams("top_deals")),
+]);
+```
+
+### Watchlist Or Stall Iteration
+
+```ts
+for await (const listing of sdk.account.iterateWatchlist({
+  limit: 20,
+  state: "listed",
+  sort_by: "most_recent",
+})) {
+  console.log(listing.id);
+}
+
+for await (const listing of sdk.stall.iterateStall("76561198000000000", {
+  limit: 20,
+  type: "buy_now",
+})) {
+  console.log(listing.id);
+}
+```
+
+### Compose Search Filters With Helpers
+
+```ts
+import {
+  buildPriceRange,
+  buildStickerFilters,
+  withWearPreset,
+} from "csfloat-node-sdk";
+
+const listings = await sdk.listings.getListings({
+  ...withWearPreset({ type: "buy_now" }, "MW"),
+  ...buildPriceRange({ min_price: 500, max_price: 5_000 }),
+  ...buildStickerFilters([{ sticker_id: 85, slot: 1 }]),
+});
+```
+
+### Preview A Buy-Order Request Before Creating It
+
+```ts
+import {
+  buildSingleSkinBuyOrderExpression,
+  buildSingleSkinBuyOrderRequest,
+} from "csfloat-node-sdk";
+
+const expression = buildSingleSkinBuyOrderExpression(7, 72, {
+  stattrak: false,
+  souvenir: false,
+});
+
+const request = buildSingleSkinBuyOrderRequest(7, 72, {
+  max_price: 3,
+  quantity: 1,
+  stattrak: false,
+  souvenir: false,
+});
+
+const similar = await sdk.account.getSimilarBuyOrders({ expression }, 5);
+```
+
+### Recommender Token Loadout Flow
+
+```ts
+const recommender = await sdk.account.createRecommenderToken();
+
+const discover = await sdk.loadout.getDiscoverLoadouts({
+  limit: 5,
+  def_index: 7,
+  paint_index: 490,
+});
+
+const stickerRecommendations = await sdk.loadout.recommendStickersForSkin(
+  recommender.token,
+  7,
+  490,
+  { count: 10 },
+);
+```
+
+### Response Metadata And Rate Limits
+
+```ts
+const response = await sdk.client.getWithMetadata("me");
+
+console.log(response.meta.status);
+console.log(response.meta.rateLimit?.remaining);
+console.log(response.meta.rateLimit?.suggestedWaitMs);
+```
+
+### Schema Media Helpers
+
+```ts
+import { getCsfloatScreenshotUrls } from "csfloat-node-sdk";
+
+const screenshot = await sdk.meta.getItemExampleScreenshot({
+  def_index: 7,
+  paint_index: 490,
+});
+
+console.log(getCsfloatScreenshotUrls(screenshot));
+```
+
+### Bulk Listing Mutation
+
+```ts
+await sdk.listings.updateBulkListings([
+  { contract_id: "123", price: 1_500 },
+  { contract_id: "456", price: 2_000 },
+]);
+```
+
 ## How To Decide Between Examples And Docs
 
 - Use docs when you want concepts, boundaries, and entrypoint guidance.