Skip to content

Commit 66cce8f

Browse files
KrablanteKrablante
committed
docs: update docs for 0.9.1.5
1 parent a5e9cca commit 66cce8f

10 files changed

Lines changed: 335 additions & 4 deletions

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,17 @@ The format is based on Keep a Changelog.
66

77
## [Unreleased]
88

9+
## [0.9.1.5] - 2026-03-10
10+
11+
### Added
12+
13+
1. a new `docs/` hub with task-oriented pages for getting started, resource selection, transport/error behavior, and examples/recipes
14+
15+
### Changed
16+
17+
1. promoted documentation discoverability in the README so npm and GitHub users get direct links into the structured docs instead of only one long landing page
18+
2. package publishing now includes `docs/` so the same documentation structure can ship with the npm tarball instead of living only in the GitHub repo
19+
920
## [0.9.1] - 2026-03-10
1021

1122
### Added

‎README.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,23 @@ The project is intentionally conservative about claims. Anything called `impleme
1919

2020
> The goal is simple: be the SDK you reach for first if you want serious CSFloat automation instead of a thin wrapper.
2121
>
22-
> Install from npm: [`csfloat-node-sdk@0.9.1`](https://www.npmjs.com/package/csfloat-node-sdk)
22+
> Install from npm: [`csfloat-node-sdk@0.9.1.5`](https://www.npmjs.com/package/csfloat-node-sdk)
23+
24+
## Documentation
25+
26+
If you want the fastest path through the SDK, start here:
27+
28+
1. [Documentation Hub](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/README.md)
29+
2. [Getting Started](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/getting-started.md)
30+
3. [Resources And Workflows](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/resources-and-workflows.md)
31+
4. [Transport, Errors, And Metadata](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/transport-and-errors.md)
32+
5. [Examples And Recipes](https://github.com/Krablante/csfloat-node-sdk/blob/main/docs/examples-and-recipes.md)
33+
6. [API Coverage Matrix](https://github.com/Krablante/csfloat-node-sdk/blob/main/API_COVERAGE.md)
34+
35+
Current recommendation:
36+
37+
1. keep documentation GitHub/npm-first while the information architecture is still evolving
38+
2. only add a separate docs site later, using this same Markdown content as the source of truth
2339

2440
## Why Choose This SDK
2541

‎docs/README.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Documentation Hub
2+
3+
This SDK already ships a broad surface. The fastest way to make it usable is not
4+
to make the main README even longer, but to give users a clear map.
5+
6+
If you are reading this on npm:
7+
8+
1. start with the repository README for the high-level pitch and install snippet
9+
2. use this `docs/` directory for task-oriented guidance
10+
3. use `API_COVERAGE.md` when you need endpoint-level truth
11+
12+
## Start Here
13+
14+
- [Getting Started](./getting-started.md)
15+
First install, API key setup, first requests, local verification.
16+
- [Resources And Workflows](./resources-and-workflows.md)
17+
Which SDK surface to use for market reads, account automation, loadouts, and higher-level helpers.
18+
- [Transport, Errors, And Metadata](./transport-and-errors.md)
19+
Retries, pacing, typed errors, and the new opt-in response metadata surface.
20+
- [Examples And Recipes](./examples-and-recipes.md)
21+
Examples, CLI commands, and which script to run for common tasks.
22+
23+
## How To Read This SDK
24+
25+
Use the SDK in three layers:
26+
27+
1. `CsfloatSdk` resources for normal application code
28+
2. helpers/builders/workflows when you want less glue code
29+
3. `sdk.client.*WithMetadata()` when you need low-level response visibility
30+
31+
## Where Different Kinds Of Truth Live
32+
33+
- Product overview: `README.md`
34+
- Stable endpoint coverage notes: `API_COVERAGE.md`
35+
- Release history: `CHANGELOG.md`
36+
- Task-oriented usage: `docs/*.md`
37+
- Executable examples: `examples/*.mjs`
38+
39+
## Should You Build A Separate Docs Site?
40+
41+
Not yet, unless you are ready to keep GitHub, npm, and the site in sync.
42+
43+
The better near-term strategy is:
44+
45+
1. keep GitHub + npm-readable docs as the source of truth
46+
2. keep docs in Markdown inside the package repository
47+
3. only later add a Vercel-hosted site that reuses this same content
48+
49+
That way npm users are not forced onto an external site just to understand the
50+
package, and a future docs site becomes a presentation layer, not a second
51+
documentation system.

‎docs/examples-and-recipes.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Examples And Recipes
2+
3+
## Shipped Examples
4+
5+
These examples are already publishable and included in the npm tarball:
6+
7+
- `examples/basic.mjs`
8+
- `examples/market-public-feeds.mjs`
9+
- `examples/watchlist-stall-iteration.mjs`
10+
- `examples/loadout-companion.mjs`
11+
- `examples/buy-order-expression.mjs`
12+
- `examples/workflows.mjs`
13+
14+
## Example Commands
15+
16+
```bash
17+
npm run example:basic
18+
npm run example:market
19+
npm run example:watchlist
20+
npm run example:loadout
21+
npm run example:buy-order
22+
npm run example:workflows
23+
```
24+
25+
## CLI Commands
26+
27+
```bash
28+
node dist/cli.js help
29+
node --env-file=.env dist/cli.js feeds
30+
node --env-file=.env dist/cli.js workspace
31+
node --env-file=.env dist/cli.js buy-order-similar --def-index 7 --paint-index 72 --stattrak false --souvenir false
32+
```
33+
34+
## Recommended Recipe Paths
35+
36+
- Public feed snapshot:
37+
`examples/market-public-feeds.mjs`
38+
- Authenticated watchlist + stall iteration:
39+
`examples/watchlist-stall-iteration.mjs`
40+
- Loadout discover / recommend flows:
41+
`examples/loadout-companion.mjs`
42+
- Expression-backed buy-order research:
43+
`examples/buy-order-expression.mjs`
44+
- Higher-level multi-call orchestration:
45+
`examples/workflows.mjs`
46+
47+
## How To Decide Between Examples And Docs
48+
49+
- Use docs when you want concepts, boundaries, and entrypoint guidance.
50+
- Use examples when you want something runnable immediately.
51+
- Use `API_COVERAGE.md` when you need route-level certainty.

‎docs/getting-started.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Getting Started
2+
3+
## Install
4+
5+
```bash
6+
npm install csfloat-node-sdk
7+
```
8+
9+
## Configure
10+
11+
Create `.env` from `.env.example`:
12+
13+
```bash
14+
CSFLOAT_API_KEY=your_api_key_here
15+
```
16+
17+
## First Client
18+
19+
```ts
20+
import { CsfloatSdk } from "csfloat-node-sdk";
21+
22+
const sdk = new CsfloatSdk({
23+
apiKey: process.env.CSFLOAT_API_KEY!,
24+
minRequestDelayMs: 1250,
25+
maxRetries: 2,
26+
retryDelayMs: 250,
27+
});
28+
```
29+
30+
## First Useful Calls
31+
32+
```ts
33+
const me = await sdk.account.getMe();
34+
const inventory = await sdk.inventory.getInventory();
35+
const listings = await sdk.listings.getListings({
36+
limit: 10,
37+
type: "buy_now",
38+
});
39+
const rates = await sdk.meta.getExchangeRates();
40+
```
41+
42+
## Recommended First Paths
43+
44+
- Public market scan: `sdk.listings.getListings()` or `sdk.workflows.getPublicMarketFeeds()`
45+
- Account dashboard snapshot: `sdk.workflows.getAccountWorkspace()`
46+
- Buy-order insight lookup: `sdk.workflows.getSingleSkinBuyOrderInsights()`
47+
- Public loadout discovery: `sdk.loadout.getDiscoverLoadouts()`
48+
49+
## Local Verification
50+
51+
```bash
52+
npm test
53+
npm run check
54+
npm run build
55+
```
56+
57+
For a publish-ready gate:
58+
59+
```bash
60+
npm run release:check
61+
```
62+
63+
## When To Leave The README
64+
65+
Use the README for overview. Switch to the docs pages when you need:
66+
67+
- a clearer map of resources and workflows
68+
- transport/error behavior
69+
- executable examples and recipes

‎docs/resources-and-workflows.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Resources And Workflows
2+
3+
## Core Resources
4+
5+
- `sdk.meta`
6+
Schema, exchange rates, app/location/bootstrap metadata, inspect helpers.
7+
- `sdk.listings`
8+
Market reads, bids, buy-now purchases, listing creation and updates.
9+
- `sdk.account`
10+
Authenticated account reads and writes: trades, offers, watchlist, buy orders, tokens, notifications, transactions.
11+
- `sdk.inventory`
12+
Authenticated inventory reads.
13+
- `sdk.stall`
14+
Public stall reads and cursor iteration.
15+
- `sdk.users`
16+
Public user profile reads.
17+
- `sdk.history`
18+
Sales history and graph helpers.
19+
- `sdk.loadout`
20+
Public and bearer-token companion loadout flows.
21+
22+
## When To Use Workflows
23+
24+
Use `sdk.workflows` when you want an opinionated multi-call helper instead of
25+
manual orchestration.
26+
27+
- `getPublicMarketFeeds()`
28+
Good for scanners, dashboards, and bots that want a single public snapshot.
29+
- `getAccountWorkspace()`
30+
Good for authenticated dashboards and operator tooling.
31+
- `getSingleSkinBuyOrderInsights()`
32+
Good for finding similar buy orders plus matching listings from a single skin input.
33+
34+
## When To Use Builders
35+
36+
Use builders when the API contract is real but awkward to compose manually.
37+
38+
- `buy-order.ts`
39+
Expression-backed buy-order request building.
40+
- `market.ts`
41+
Query presets and filter composition.
42+
- `loadout.ts`
43+
Recommendation and discover-mode helper builders.
44+
- `schema.ts`
45+
Schema lookup helpers and screenshot URL helpers.
46+
47+
## Suggested Reading Order
48+
49+
1. `README.md`
50+
2. `docs/getting-started.md`
51+
3. this file
52+
4. `docs/transport-and-errors.md`
53+
5. `docs/examples-and-recipes.md`
54+
6. `API_COVERAGE.md` for endpoint-level details

‎docs/transport-and-errors.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Transport, Errors, And Metadata
2+
3+
## Transport Defaults
4+
5+
The SDK already ships safer defaults than a thin wrapper:
6+
7+
- timeout handling
8+
- retry/backoff for safe requests
9+
- optional client-side pacing with `minRequestDelayMs`
10+
- typed error classification
11+
- custom `fetch` / dispatcher support
12+
13+
## Error Model
14+
15+
Non-2xx responses throw `CsfloatSdkError`.
16+
17+
Important fields:
18+
19+
- `status`
20+
- `code`
21+
- `kind`
22+
- `retryable`
23+
- `apiMessage`
24+
- `details`
25+
26+
Typical `kind` values:
27+
28+
- `validation`
29+
- `authentication`
30+
- `authorization`
31+
- `account_gated`
32+
- `role_gated`
33+
- `not_found`
34+
- `rate_limit`
35+
- `server`
36+
- `timeout`
37+
- `network`
38+
39+
## Opt-In Response Metadata
40+
41+
Most users should keep using normal resource methods.
42+
43+
If you need low-level response visibility, use the new client methods:
44+
45+
```ts
46+
import { CsfloatSdk, type CsfloatMeResponse } from "csfloat-node-sdk";
47+
48+
const sdk = new CsfloatSdk({
49+
apiKey: process.env.CSFLOAT_API_KEY!,
50+
});
51+
52+
const response = await sdk.client.getWithMetadata<CsfloatMeResponse>("me");
53+
54+
console.log(response.data.user.steam_id);
55+
console.log(response.meta.status);
56+
console.log(response.meta.rateLimit?.remaining);
57+
console.log(response.meta.rateLimit?.resetAt);
58+
```
59+
60+
Available methods:
61+
62+
- `getWithMetadata()`
63+
- `postWithMetadata()`
64+
- `patchWithMetadata()`
65+
- `putWithMetadata()`
66+
- `deleteWithMetadata()`
67+
68+
## When Metadata Is Worth Using
69+
70+
- bots that want explicit rate-limit visibility
71+
- operator tooling
72+
- debugging edge cases on gated routes
73+
- telemetry or internal wrappers built on top of this SDK
74+
75+
## When Not To Use It
76+
77+
Do not rewrite all application code around raw metadata if you do not need it.
78+
For most consumers, resource methods plus typed errors remain the cleaner API.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "csfloat-node-sdk",
3-
"version": "0.9.1",
3+
"version": "0.9.1.5",
44
"description": "Live-validated Node.js / TypeScript SDK for the CSFloat API and public companion surfaces.",
55
"homepage": "https://github.com/Krablante/csfloat-node-sdk",
66
"repository": {
@@ -27,6 +27,7 @@
2727
},
2828
"files": [
2929
"dist",
30+
"docs",
3031
"examples",
3132
"API_COVERAGE.md",
3233
"CHANGELOG.md",

‎src/client.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { CsfloatSdkError, type CsfloatErrorKind } from "./errors.js";
22
import type { QueryParams } from "./types.js";
33
import { cleanParams } from "./utils.js";
44

5-
const DEFAULT_USER_AGENT = "csfloat-node-sdk/0.9.1";
5+
const DEFAULT_USER_AGENT = "csfloat-node-sdk/0.9.1.5";
66
const DEFAULT_MAX_RETRIES = 2;
77
const DEFAULT_RETRY_DELAY_MS = 250;
88
const DEFAULT_MAX_RETRY_DELAY_MS = 2_000;

‎test/client.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ describe("CsfloatHttpClient", () => {
2828
method: "GET",
2929
headers: expect.objectContaining({
3030
Authorization: "secret",
31-
"User-Agent": "csfloat-node-sdk/0.9.1",
31+
"User-Agent": "csfloat-node-sdk/0.9.1.5",
3232
}),
3333
});
3434
});

0 commit comments

Comments
 (0)