@proxyrequest/sdk 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Fixed
+
+- Keep the exported `SDK_VERSION` synchronized with the package version and verify it in the package smoke test.
+
+## [2.1.0] - 2026-09-17
+
+- Add atomic per-package data reset with typed requests, response metadata, and idempotent retries.
+- Refresh the public API contract and document root balances versus child allocations.
+
+## [2.0.0] - 2026-09-16
+
+### Changed
+
+- Replace the incorrect webhook verifier with the actual `X-Signature`
+  Base64 HMAC-SHA256 format over exact raw bytes.
+
+- Regenerated from the public backend contract (81 operations, 130 schemas).
+- Added the optional `pending`/`paid` status to invoice creation requests.
+- Removed the disabled sessions-management resource; 79 supported operations remain.
+- Corrected OTP login unions, MFA request bodies, payment fields, nullable invoices,
+  and configuration-dependent user/invoice responses.
+- Replaced fixed contract-size gates with operation-ID and coverage validation.
+- Added backend-serializer fixtures and compatibility regression tests.
+
+### Added
+
+- Automatic and explicit idempotency keys with bounded ambiguous-outcome retries.
+- Response metadata variants and explicit ETag/`If-Match` optimistic concurrency support.
+
 ## [1.0.0] - 2026-08-21
 
 ### Added
@@ -13,4 +44,6 @@ All notable changes to this project are documented here. The format follows [Kee
 - Normalized errors, lazy pagination, invoice downloads, raw requests, and webhook verification.
 - Reproducible OpenAPI generation, package validation, Node/browser tests, CI, and npm provenance workflow.
 
+[Unreleased]: https://github.com/proxyrequest/javascript-sdk/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/proxyrequest/javascript-sdk/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/proxyrequest/javascript-sdk/releases/tag/v1.0.0

package/README.md

@@ -14,7 +14,7 @@ The official TypeScript SDK for the [ProxyRequest public API](https://proxyreque
 - customer and sub-user accounts;
 - packages, traffic allocations, connection limits, and proxy credentials;
 - invoices, payment links, coupons, rewards, and reseller workflows;
-- residential and static ISP proxy inventory, targeting, routing, and sessions;
+- residential and static ISP proxy inventory, targeting, routing, and sticky proxy credentials;
 - usage accounting, analytics, operational visibility, and webhooks;
 - dashboard, branding, API automation, and Telegram integration.
 
@@ -80,11 +80,17 @@ Public login, signup, locations, and similar calls can use an anonymous client:
 const client = ProxyRequestClient.anonymous();
 ```
 
-Never embed a Static API key, Telegram service secret, or webhook secret in frontend JavaScript. Browser support is intended for anonymous or appropriately scoped end-user token flows. See the service documentation on [authentication and API fundamentals](https://proxyrequest.com/docs/integration/api-fundamentals/).
+Never embed a Static API key or webhook secret in frontend JavaScript. Browser support is intended for anonymous or appropriately scoped end-user token flows. See the service documentation on [authentication and API fundamentals](https://proxyrequest.com/docs/integration/api-fundamentals/).
 
 ## Resource API
 
-The client exposes all 82 operations through 19 resource groups:
+The client exposes 80 supported operations through 17 resource groups. The pinned
+public schema contains 82 operations; the disabled `sessions_list` and
+`sessions_destroy` operations are intentionally excluded from the SDK. Sticky
+session options in proxy generation remain supported.
+
+See [backend compatibility and MFA](docs/backend-compatibility.md) for the updated
+login flow, variable response models, and migration notes.
 
 ```ts
 client.apiKeys;
@@ -100,10 +106,8 @@ client.packages;
 client.profile;
 client.proxies;
 client.rewards;
-client.sessions;
 client.settings;
 client.telegram;
-client.telegramService;
 client.users;
 client.webhooks;
 ```
@@ -173,6 +177,36 @@ console.log(generated.proxies);
 
 See [catalog and proxies](https://proxyrequest.com/docs/integration/catalog-and-proxies/) and the separate [proxy connection documentation](https://proxyrequest.com/docs/proxy/authentication/).
 
+## Automatic retries and optimistic concurrency
+
+The SDK automatically protects supported writes during up to three total
+attempts after a network failure, or after `409 Conflict` with a numeric
+`Retry-After` of at most five seconds. Other HTTP errors are returned
+immediately. This protection applies inside one running call. If the process
+stops before saving the result, inspect the affected resource before submitting
+another write:
+
+```ts
+const response = await client.invoices.createWithResponse({
+  body: { gateway: "stripe", package_id: packageId },
+});
+
+console.log(response.data.id, response.etag);
+```
+
+Every generated method also has a `WithResponse` variant exposing `statusCode`,
+`headers`, and `etag`.
+
+Updates and deletes that declare `If-Match` accept the latest strong ETag:
+
+```ts
+await client.users.update({ id: userId, ifMatch: response.etag, body: changes });
+```
+
+A stale value raises `ApiError` with `kind === "precondition"` and the current
+server ETag in `currentEtag`. The SDK deliberately does not cache ETags: callers
+choose which representation is being updated.
+
 ## Pagination
 
 List methods return the API page model. Use `client.paginate()` when you want a lazy async stream:
@@ -205,7 +239,7 @@ try {
 }
 ```
 
-Kinds include `validation`, `authentication`, `permission`, `not_found`, `conflict`, `rate_limit`, `server`, `network`, and `unexpected`. The SDK does not retry or refresh tokens automatically. See [common integration errors](https://proxyrequest.com/docs/integration/common-errors/).
+Kinds include `validation`, `authentication`, `permission`, `not_found`, `conflict`, `precondition`, `rate_limit`, `server`, `network`, and `unexpected`. Supported writes receive bounded automatic retries for transient failures; tokens are never refreshed automatically. See [common integration errors](https://proxyrequest.com/docs/integration/common-errors/).
 
 ## Per-request controls and custom Fetch
 
@@ -253,12 +287,12 @@ import { WebhookVerifier } from "@proxyrequest/sdk";
 
 const event = await WebhookVerifier.decodeVerifiedJson(
   rawBody,
-  request.headers.get("ProxyRequest-Signature") ?? "",
+  request.headers.get("X-Signature") ?? "",
   process.env.PROXYREQUEST_WEBHOOK_SECRET!,
 );
 ```
 
-Verification supports the `t=...,v1=...` format, multiple `v1` values, Web Crypto HMAC-SHA256, and a default five-minute tolerance. See the [webhook integration guide](https://proxyrequest.com/docs/integration/webhooks/) and [event reference](https://proxyrequest.com/docs/reference/webhook-events/).
+Deliveries use standard padded Base64 HMAC-SHA256 over the raw body, without a signed timestamp. Verification accepts only this current format. It authenticates the body, but does not prevent replay: deduplicate usage events in your application. These helpers require SDK 2.0.0 or newer; version 1.0.0 does not support the current delivery format. See the [webhook integration guide](https://proxyrequest.com/docs/integration/webhooks/) and [event reference](https://proxyrequest.com/docs/reference/webhook-events/).
 
 ## Raw requests
 
@@ -317,3 +351,19 @@ The repository also has a real Chromium smoke test via `npm run test:browser`.
 ## License
 
 [MIT](LICENSE)
+
+## Reset remaining data (SDK 2.1.0+)
+
+```typescript
+const order = await client.users.resetData({
+  id: userId,
+  body: { package_id: packageId },
+  idempotencyKey: resetOperationId,
+});
+```
+
+Send only `package_id`, without `data`. A system administrator can reset any user; other accounts can reset only their direct children. The server atomically clears positive, zero, or negative remaining data for a finite package and returns the updated order. Unlimited packages are rejected. Root orders lose their remaining ledger balances; child orders lose their remaining quota without changing the parent pool. Usage history and invoices are preserved.
+
+Persist one operation ID and reuse it when retrying the same reset, including after a process restart. This prevents a repeated request from clearing a later top-up. Use subtraction when an explicit amount should be removed from a child quota. The backend must support the reset endpoint before calling it.
+
+Version 2.1 retains legacy user and invoice models from 2.0 for compatibility with older deployments. These compatibility types do not change the current public API contract.

package/SECURITY.md

@@ -10,4 +10,4 @@ Do not open a public issue for a vulnerability. Email `support@proxyrequest.com`
 
 ## Credential handling
 
-Static API keys, Telegram service secrets, and webhook secrets belong only in trusted server environments. Rotate any credential that may have been exposed and remove it from Git history and build artifacts. Bearer tokens used in browsers should be short-lived and scoped according to the ProxyRequest API documentation.
+Static API keys and webhook secrets belong only in trusted server environments. Rotate any credential that may have been exposed and remove it from Git history and build artifacts. Bearer tokens used in browsers should be short-lived and scoped according to the ProxyRequest API documentation.