@limitry/sdk 1.0.0-rc.1 → 1.0.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+What changed in the Limitry TypeScript SDK (`@limitry/sdk`). Generated from the source on each release; newest first.
+
+## 1.0.0-rc.4 (2026-10-16)
+
+### Added
+
+- Each release comes with a `CHANGELOG.md` listing what changed, newest first.
+
+### Changed
+
+- The package page (README, on GitHub, npm and PyPI) shows what the product does with a first real example, and links the guide, the API reference, the changelog and support.
+
+## 1.0.0-rc.3 (2026-10-16)
+
+No user-facing changes.

package/README.md

@@ -1,26 +1,99 @@
 # @limitry/sdk
 
-The official TypeScript client for the Limitry API.
+The Limitry TypeScript SDK puts a limit around costly work in one call: `guard` checks before your code runs, and `hold` reserves an estimate, then charges what the work actually cost. Every API operation is a typed method too.
+
+Limitry is the limits, credits and budgets layer for your software: give each of your users, teams, tenants, API keys or agents an allowance, and before any costly action one call tells your code whether it may happen.
+
+## Install
 
 ```bash
 npm install @limitry/sdk
 ```
 
+Set `LIMITRY_API_KEY` to a key from **API keys** in the app. Use a test
+key (`lim_test_…`) while you build.
+
+## Guard costly work
+
+`guard` checks the limit, then runs your code only if it's allowed. Here
+it counts one AI call against a limit such as 100 a day:
+
+```ts
+import { createClient, LimitExceeded } from "@limitry/sdk";
+
+const limitry = createClient(); // reads LIMITRY_API_KEY
+
+try {
+  const reply = await limitry.guard(
+    { subject: { kind: "user", id: "usr_123" }, action: "ai-call" },
+    () => callModel(prompt),
+  );
+} catch (error) {
+  if (error instanceof LimitExceeded) {
+    console.log(`Try again in ${error.retryAfterSeconds} seconds`);
+  }
+}
+```
+
+## Charge what it actually cost
+
+When you only know the cost afterwards, such as an AI reply priced by
+the token, `hold` reserves an estimate (5 cents here), runs your code
+and charges what it used. If your code throws, the hold is released:
+
 ```ts
 import { createClient } from "@limitry/sdk";
 
-// The key from LIMITRY_API_KEY, or pass { token }.
 const limitry = createClient();
+
+const answer = await limitry.hold(
+  { subject: { kind: "user", id: "usr_123" }, action: "ai-call", estimate: 5 },
+  async (held) => {
+    const response = await callModel(prompt);
+    held.cost(priceCents(response.usage)); // your prices, in cents
+    return response;
+  },
+);
 ```
 
-- Guide: https://limitry.com/docs/sdk/
-- API reference: https://api.limitry.com/v1/docs
+If Limitry can't be reached, each limit's fail mode decides: `open` lets
+the work run, `closed` refuses it.
 
-## Building from this repository
+## Everything else
 
-```bash
-npm ci && npm test && npm run build
+Every API operation is a typed method, named like its CLI command:
+`limitry limits create` is `limitry.limits.create()`.
+
+```ts
+import { createClient } from "@limitry/sdk";
+
+const limitry = createClient();
+
+await limitry.limits.create({
+  name: "AI replies per day",
+  subjectKind: "user",
+  action: "ai-call",
+  amount: 100,
+  window: "day",
+});
 ```
 
-This repository is generated from Limitry's own repository on
-each release; see CONTRIBUTING.md. Licensed under the Apache License 2.0.
+A failure throws an `ApiError` with the error's `code`, `message`,
+`status` and `requestId`. Writes are retried safely: each sends an
+idempotency key, so a retried request happens once.
+
+## Links
+
+- [Website](https://limitry.com)
+- [TypeScript SDK guide](https://limitry.com/docs/sdk/)
+- [API reference](https://limitry.com/docs/reference/)
+- [Changelog](https://github.com/limitry/limitry-typescript/blob/main/CHANGELOG.md)
+- [Discord](https://limitry.com/discord)
+- [Report a security issue](https://limitry.com/security/)
+
+## About this package
+
+This repository is generated from Limitry's source on each
+release, so pull requests are ported there and credited (see
+[CONTRIBUTING.md](https://github.com/limitry/limitry-typescript/blob/main/CONTRIBUTING.md)).
+Licensed under the Apache License 2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limitry/sdk",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.4",
   "description": "Limitry API client",
   "type": "module",
   "exports": {
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "NOTICE"
+    "NOTICE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",