@workoutx/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## 0.1.0
+
+Initial release.
+
+- Exercises: `list`, `get`, `byName`, `byBodyPart`, `byTarget`, `byEquipment`,
+  `search`, `similar`, `alternatives`, `calories`, `changes`, `find`, and the
+  `bodyPartList` / `targetList` / `equipmentList` / `secondaryMuscleList` lookups.
+- GIFs: raw byte fetch and direct URL builder.
+- Workout generator and supplement endpoints.
+- Body Scan: credits, profile, history, key management, checkout, public packs.
+- Account (`auth`): register, login, profile, API-key management, password
+  reset, email verification, usage stats, and webhook configuration.
+- Billing: subscription status, Stripe Checkout, and customer portal.
+- Automatic retry with backoff on transient failures (429/5xx/network),
+  honoring `Retry-After`.
+- Shared Bearer token: a successful `auth.login()` is cached for later
+  `scan` / `billing` calls.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WorkoutX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @workoutx/sdk
+
+Official TypeScript/JavaScript SDK for the [WorkoutX API](https://workoutxapp.com).
+One client covers **both** products:
+
+- **Exercises** — exercises, GIFs, workout generator, supplements (API-key auth)
+- **Body Scan** — credits, history, keys, checkout (logged-in user / Bearer auth)
+- **Account & Billing** — register/login, API-key management, password reset, webhooks, subscription checkout (Bearer auth)
+
+Works in Node.js 18+ and modern browsers. Zero runtime dependencies (uses native `fetch`).
+
+## Install
+
+```bash
+npm install @workoutx/sdk
+```
+
+## Quick start
+
+```ts
+import { WorkoutX } from "@workoutx/sdk";
+
+const wx = new WorkoutX({
+  apiKey: "wx_your_key_here",        // exercises / gifs / workout / supplements
+  scan: { token: "eyJ..." },          // body scan (optional)
+});
+
+// Exercises
+const page    = await wx.exercises.list({ limit: 20 });
+const byId    = await wx.exercises.get("0001");
+const lunges  = await wx.exercises.byName("lunges");   // ← name lookup
+const similar = await wx.exercises.similar("0001");
+const alts    = await wx.exercises.alternatives("0001", { equipment: "dumbbell" });
+
+// GIFs (binary)
+const bytes = await wx.gifs.get("0001");                // ArrayBuffer
+const src   = wx.gifUrl("0001");                        // for <img src>
+
+// Workout & supplements
+const workout = await wx.workout.generate({ goal: "hypertrophy", days: 4 });
+const stack   = await wx.supplements.stack({ goal: "cut" });
+
+// Body Scan
+const credits = await wx.scan.credits();
+const history = await wx.scan.history({ limit: 10 });
+
+// Account & billing
+const { token } = await wx.auth.login("user@example.com", "•••"); // token cached for scan/auth/billing
+const me        = await wx.auth.me();
+const keys      = await wx.auth.listKeys();
+const sub       = await wx.billing.status();
+const checkout  = await wx.billing.checkout("pro", "yearly");      // → { url } to redirect to Stripe
+```
+
+## Authentication
+
+The two products use different credentials — the SDK handles both transparently.
+
+| Product | Endpoints | Credential |
+|---------|-----------|------------|
+| Exercises | `exercises`, `gifs`, `workout`, `supplements` | `apiKey` (`wx_...`) → `X-WorkoutX-Key` header |
+| Body Scan | `scan.*` | Bearer JWT |
+
+For Body Scan you can either pass a ready token or let the SDK log in for you:
+
+```ts
+// Option A — you already have a token
+new WorkoutX({ apiKey, scan: { token: "eyJ..." } });
+
+// Option B — auto-login on first scan call, then cache the token
+new WorkoutX({ apiKey, scan: { email: "user@example.com", password: "•••" } });
+```
+
+You can also set/replace the token later:
+
+```ts
+wx.setScanToken("eyJ...");
+```
+
+## Avoiding the "name as ID" 404
+
+`exercises.get(id)` expects an exact numeric ID (IDs have gaps and are **not**
+sequential). Passing a human name like `"lunges"` returns 404. Use `byName`, or
+the convenience resolver that tries an ID first then falls back to a name search:
+
+```ts
+const ex = await wx.exercises.find("lunges"); // Exercise | null
+```
+
+## Error handling
+
+Every non-2xx response throws a `WorkoutXError` with structured fields:
+
+```ts
+import { WorkoutXError } from "@workoutx/sdk";
+
+try {
+  await wx.exercises.get("not-a-real-id");
+} catch (err) {
+  if (err instanceof WorkoutXError) {
+    err.status;        // 404
+    err.code;          // "Not Found"
+    err.message;       // human-readable
+    err.tip;           // hint from the API, when present
+    err.isNotFound;    // boolean helpers: isAuthError, isRateLimited, isNotFound
+  }
+}
+```
+
+Transient failures (HTTP 429 and 5xx, plus network errors) are retried
+automatically with exponential backoff, honoring the `Retry-After` header.
+
+## Options
+
+```ts
+new WorkoutX({
+  apiKey,
+  scan,
+  baseUrl: "https://api.workoutxapp.com", // default
+  timeout: 30_000,                         // ms, default 30s
+  maxRetries: 2,                           // default 2
+  headers: { "X-Trace": "abc" },           // extra headers on every request
+  fetch: customFetch,                      // custom fetch impl (optional)
+});
+```
+
+## API surface
+
+- `wx.exercises` — `list`, `get`, `byName`, `byBodyPart`, `byTarget`, `byEquipment`, `search`, `similar`, `alternatives`, `calories`, `changes`, `find`, `bodyPartList`, `targetList`, `equipmentList`, `secondaryMuscleList`
+- `wx.gifs` — `get`, `url`
+- `wx.workout` — `generate`, `program`
+- `wx.supplements` — `list`, `filters`, `stack`, `forExercise`, `get`
+- `wx.scan` — `credits`, `me`, `history`, `listKeys`, `createKey`, `deleteKey`, `checkout`, `packs`
+- `wx.auth` — `register`, `login`, `me`, `updateMe`, `changePassword`, `listKeys`, `createKey`, `deleteKey`, `updateKeyPlan`, `usage`, `forgotPassword`, `resetPassword`, `verifyEmail`, `resendVerification`, `getWebhook`, `setWebhook`, `testWebhook`
+- `wx.billing` — `status`, `checkout`, `portal`
+
+> `auth`, `billing`, and `scan` use the same Bearer token. A successful
+> `auth.login()` caches it, so subsequent `scan.*` / `billing.*` calls work
+> without re-supplying credentials. Google OAuth (`/v1/auth/google`) is a
+> browser-redirect flow and is intentionally not wrapped in the SDK.
+
+> Some endpoints are plan-gated (e.g. `search`, `workout.generate`,
+> `supplements.stack`). Calling them on a plan without the feature returns a
+> `WorkoutXError` with a `403`/upgrade message.
+
+## License
+
+MIT