@workoutx/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,442 @@
+type QueryValue = string | number | boolean | undefined | null;
+type Query = Record<string, QueryValue>;
+interface HttpConfig {
+    baseUrl: string;
+    /** API key for exercises/gifs/workout/supplements (sent as X-WorkoutX-Key). */
+    apiKey?: string;
+    /** Bearer token for the body-scan endpoints. */
+    getBearer?: () => Promise<string | undefined> | string | undefined;
+    /** Per-request timeout in ms. Default 30000. */
+    timeout: number;
+    /** Max retries for transient failures (429 / 5xx / network). Default 2. */
+    maxRetries: number;
+    /** Extra headers merged into every request. */
+    defaultHeaders: Record<string, string>;
+    fetch: typeof fetch;
+}
+interface RequestOptions {
+    method?: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+    query?: Query;
+    body?: unknown;
+    /** Which credential to attach. "key" = X-WorkoutX-Key, "bearer" = Authorization. */
+    auth?: "key" | "bearer";
+    /** Override the default Accept/return handling to get raw bytes. */
+    raw?: boolean;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    request<T>(path: string, opts?: RequestOptions): Promise<T>;
+    private resolveBearer;
+}
+
+/**
+ * Shared types for the WorkoutX SDK.
+ *
+ * These mirror the shapes returned by the WorkoutX API
+ * (https://api.workoutxapp.com). Fields that depend on the caller's plan
+ * (e.g. extended metadata only available on paid tiers) are marked optional.
+ */
+/** Firestore-style timestamp returned by the API. */
+interface ApiTimestamp {
+    _seconds: number;
+    _nanoseconds: number;
+}
+/** A single exercise record. */
+interface Exercise {
+    id: string;
+    name: string;
+    bodyPart: string;
+    equipment: string;
+    target: string;
+    secondaryMuscles: string[];
+    instructions: string[];
+    gifUrl?: string;
+    createdAt?: ApiTimestamp;
+    updatedAt?: ApiTimestamp;
+    /** Plan-gated / computed fields may also appear depending on the endpoint. */
+    [key: string]: unknown;
+}
+/** Standard paginated list envelope used by exercise list endpoints. */
+interface PaginatedList<T> {
+    total: number;
+    count: number;
+    data: T[];
+}
+/** Common pagination params accepted by list endpoints. */
+interface PageParams {
+    limit?: number;
+    offset?: number;
+}
+/** Query params for {@link ExercisesResource.search}. */
+interface SearchParams extends PageParams {
+    name?: string;
+    bodyPart?: string;
+    target?: string;
+    equipment?: string;
+    secondaryMuscle?: string;
+    /** Ultra-gated filters — only effective on plans that allow them. */
+    jointFocus?: string;
+    intensityLevel?: string;
+    movementTag?: string;
+}
+/** Query params for {@link ExercisesResource.alternatives}. */
+interface AlternativesParams extends PageParams {
+    /** Prefer alternatives using this equipment. */
+    equipment?: string;
+    /** Exclude alternatives using this equipment. */
+    excludeEquipment?: string;
+}
+/** Result of an exercise calorie estimate. */
+interface CalorieEstimate {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+/** A supplement record. */
+interface Supplement {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+/** Params for {@link WorkoutResource.generate}. */
+interface WorkoutGenerateParams {
+    goal?: string;
+    days?: number;
+    equipment?: string;
+    level?: string;
+    [key: string]: unknown;
+}
+/** Params for {@link WorkoutResource.program}. */
+interface WorkoutProgramParams {
+    goal?: string;
+    weeks?: number;
+    daysPerWeek?: number;
+    [key: string]: unknown;
+}
+/** Generic JSON object response for endpoints with flexible shapes. */
+type JsonObject = Record<string, unknown>;
+
+/** Access to `/v1/exercises/*`. Authenticated with the API key. */
+declare class ExercisesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List exercises (paginated). */
+    list(params?: PageParams): Promise<PaginatedList<Exercise>>;
+    /**
+     * Look up a single exercise by its exact numeric ID (e.g. "0001").
+     *
+     * Note: IDs are not sequential — there are gaps. To resolve a human name
+     * like "lunges", use {@link byName} instead. See {@link find} for a helper
+     * that tries an ID first and falls back to a name search.
+     */
+    get(id: string): Promise<Exercise>;
+    /** Find exercises whose name contains the given text. */
+    byName(name: string, params?: PageParams): Promise<Exercise[]>;
+    /** Filter exercises by body part (e.g. "back"). */
+    byBodyPart(bodyPart: string, params?: PageParams): Promise<PaginatedList<Exercise>>;
+    /** Filter exercises by target muscle (e.g. "abs"). */
+    byTarget(target: string, params?: PageParams): Promise<PaginatedList<Exercise>>;
+    /** Filter exercises by equipment (e.g. "barbell"). */
+    byEquipment(equipment: string, params?: PageParams): Promise<PaginatedList<Exercise>>;
+    /** Multi-filter search (plan-gated: requires the `multiFilter` feature). */
+    search(params?: SearchParams): Promise<PaginatedList<Exercise>>;
+    /** Exercises similar to the given exercise ID. */
+    similar(id: string, params?: PageParams): Promise<PaginatedList<Exercise>>;
+    /** Alternatives that hit the same target with different equipment. */
+    alternatives(id: string, params?: AlternativesParams): Promise<PaginatedList<Exercise>>;
+    /** Estimated calories burned for an exercise. */
+    calories(id: string, params?: JsonObject): Promise<CalorieEstimate>;
+    /** Dataset changelog (plan-gated: requires the `datasetSync` feature). */
+    changes(params?: JsonObject): Promise<JsonObject>;
+    /** List of all body parts. */
+    bodyPartList(): Promise<string[]>;
+    /** List of all target muscles. */
+    targetList(): Promise<string[]>;
+    /** List of all equipment types. */
+    equipmentList(): Promise<string[]>;
+    /** List of all secondary muscles. */
+    secondaryMuscleList(): Promise<string[]>;
+    /**
+     * Convenience resolver: treat `idOrName` as an ID first, and if that 404s,
+     * fall back to a name search and return the first match. Saves callers from
+     * the common "/v1/exercises/lunges → 404" mistake.
+     *
+     * Returns `null` when neither an ID nor a name match is found.
+     */
+    find(idOrName: string): Promise<Exercise | null>;
+}
+
+/** Access to `/v1/gifs/*`. Authenticated with the API key. */
+declare class GifsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch an exercise GIF as raw bytes.
+     *
+     * Accepts both "0001" and "0001.gif". On the free plan the API serves a
+     * watermarked variant; paid plans get the original. Returns the binary
+     * payload — wrap it in `Blob`/`Buffer` as needed.
+     */
+    get(filename: string): Promise<ArrayBuffer>;
+    /**
+     * Build the direct GIF URL (no request made). Useful for `<img src>`.
+     * The API key still needs to be supplied — by default via the `api-key`
+     * query param, which works for `<img>` tags that can't set headers.
+     */
+    url(filename: string, opts: {
+        baseUrl: string;
+        apiKey?: string;
+    }): string;
+}
+
+/** Access to `/v1/workout/*`. Authenticated with the API key. */
+declare class WorkoutResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Generate a single workout (plan-gated: requires `workoutGenerator`). */
+    generate(params?: WorkoutGenerateParams): Promise<JsonObject>;
+    /** Generate a multi-week program (plan-gated: requires `workoutPrograms`). */
+    program(params?: WorkoutProgramParams): Promise<JsonObject>;
+}
+
+/** Access to `/v1/supplements/*`. Authenticated with the API key. */
+declare class SupplementsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** List supplements (paginated). */
+    list(params?: PageParams): Promise<JsonObject>;
+    /** Available supplement filters. */
+    filters(): Promise<JsonObject>;
+    /** Build a recommended stack (plan-gated: requires `supplementStacks`). */
+    stack(params?: JsonObject): Promise<JsonObject>;
+    /** Supplements recommended for a given exercise. */
+    forExercise(exerciseId: string): Promise<JsonObject>;
+    /** Get a single supplement by ID. */
+    get(id: string): Promise<Supplement>;
+}
+
+/**
+ * Access to the Body Scan product (`/v1/scan/*`).
+ *
+ * Unlike the exercise endpoints (API key), these require a logged-in user's
+ * Bearer token. Supply it via the client's `scan` option — either a ready
+ * `token`, or `email`/`password` for automatic login on first use.
+ */
+declare class ScanResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Body-scan credit balance + usage stats for the current user. */
+    credits(): Promise<JsonObject>;
+    /** Current user's body-scan profile. */
+    me(): Promise<JsonObject>;
+    /** Paginated scan history. */
+    history(params?: PageParams): Promise<JsonObject>;
+    /** List the user's body-scan API keys. */
+    listKeys(): Promise<JsonObject[]>;
+    /** Create a body-scan API key. */
+    createKey(name: string): Promise<JsonObject>;
+    /** Delete a body-scan API key by ID. */
+    deleteKey(id: string): Promise<JsonObject>;
+    /** Create a Stripe checkout session for a credit pack. */
+    checkout(body?: JsonObject): Promise<JsonObject>;
+    /** Public list of available credit packs (no auth required). */
+    packs(): Promise<JsonObject>;
+}
+
+/** Result of {@link AuthResource.login}. */
+interface AuthLoginResult extends JsonObject {
+    token: string;
+    user: JsonObject;
+    apiKeys: JsonObject[];
+}
+/**
+ * Account, API-key, and webhook management (`/v1/auth/*`).
+ *
+ * `register`, `login`, `forgotPassword`, `resetPassword`, `verifyEmail`, and
+ * `resendVerification` are public — no token needed. Everything else
+ * requires the Bearer token returned by `login` (see {@link WorkoutX.setScanToken}
+ * or pass `scan: { email, password }` to the client for automatic login).
+ *
+ * Google OAuth (`/v1/auth/google`) is a browser-redirect flow and is not
+ * wrapped here — it only makes sense from a web app, not an SDK call.
+ */
+declare class AuthResource {
+    private readonly http;
+    private readonly onLogin?;
+    constructor(http: HttpClient, onLogin?: ((token: string) => void) | undefined);
+    /** Create a new account. Sends a verification email; no token is issued yet. */
+    register(params: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<JsonObject>;
+    /** Log in and receive a Bearer token (also used by `scan.*`). */
+    login(email: string, password: string): Promise<AuthLoginResult>;
+    /** Get the current user's profile. */
+    me(): Promise<JsonObject>;
+    /** Update the current user's display name. */
+    updateMe(name: string): Promise<JsonObject>;
+    /** Change the current user's password. */
+    changePassword(currentPassword: string, newPassword: string): Promise<JsonObject>;
+    /** List the current user's API keys (exercises/gifs/workout/supplements product). */
+    listKeys(): Promise<JsonObject[]>;
+    /** Create a new API key. */
+    createKey(name?: string): Promise<JsonObject>;
+    /** Delete an API key by ID. */
+    deleteKey(id: string): Promise<JsonObject>;
+    /** Change the plan assigned to an API key. */
+    updateKeyPlan(id: string, planId: string): Promise<JsonObject>;
+    /** Usage statistics for the current user (optionally filtered to one API key). */
+    usage(params?: {
+        days?: number;
+        apiKey?: string;
+    }): Promise<JsonObject>;
+    /** Request a password-reset email. Always succeeds (no email enumeration). */
+    forgotPassword(email: string): Promise<JsonObject>;
+    /** Complete a password reset using the token emailed by `forgotPassword`. */
+    resetPassword(token: string, password: string): Promise<JsonObject>;
+    /** Verify an email address using the token from the verification email. */
+    verifyEmail(token: string): Promise<JsonObject>;
+    /** Resend the verification email. Always succeeds (no email enumeration). */
+    resendVerification(email: string): Promise<JsonObject>;
+    /** Get the current user's registered webhook URL. */
+    getWebhook(): Promise<{
+        webhookUrl: string | null;
+    }>;
+    /** Set (or clear, with `null`) the webhook URL. */
+    setWebhook(webhookUrl: string | null): Promise<JsonObject>;
+    /** Send a test event to the registered webhook URL. */
+    testWebhook(): Promise<JsonObject>;
+}
+
+/**
+ * Subscription billing (`/v1/billing/*`). All methods require the Bearer
+ * token from {@link AuthResource.login} (same token used by `scan.*`).
+ *
+ * `POST /v1/billing/webhook` (Stripe's server-to-server callback) is
+ * intentionally not wrapped here — it requires the raw request body and
+ * Stripe-Signature header from an actual HTTP server, not a client SDK call.
+ */
+declare class BillingResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Current subscription status, plan, and renewal date for the logged-in user. */
+    status(): Promise<JsonObject>;
+    /** Create a Stripe Checkout session for upgrading to a paid plan. */
+    checkout(planId: "basic" | "pro" | "ultra", billingCycle?: "monthly" | "yearly"): Promise<{
+        url: string;
+    }>;
+    /** Open the Stripe Customer Portal for the logged-in user to manage/cancel their subscription. */
+    portal(): Promise<{
+        url: string;
+    }>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.workoutxapp.com";
+/** Credentials for the Body Scan product. */
+type ScanAuth = 
+/** A ready-to-use JWT from a prior login. */
+{
+    token: string;
+}
+/** Credentials used to log in automatically on first scan call. */
+ | {
+    email: string;
+    password: string;
+};
+interface WorkoutXOptions {
+    /**
+     * API key (starts with `wx_`) for exercises, gifs, workout, supplements.
+     * Required unless you only use public endpoints (e.g. `scan.packs`).
+     */
+    apiKey?: string;
+    /** Credentials for the Body Scan product. Omit if you don't use `scan`. */
+    scan?: ScanAuth;
+    /** Override the API base URL. Defaults to https://api.workoutxapp.com */
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 30000. */
+    timeout?: number;
+    /** Max retries on transient errors (429/5xx/network). Default 2. */
+    maxRetries?: number;
+    /** Extra headers added to every request. */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+/**
+ * The WorkoutX API client. One instance covers both products:
+ *
+ * ```ts
+ * const wx = new WorkoutX({ apiKey: "wx_...", scan: { token: "eyJ..." } });
+ * await wx.exercises.byName("lunges");
+ * await wx.scan.credits();
+ * ```
+ */
+declare class WorkoutX {
+    readonly exercises: ExercisesResource;
+    readonly gifs: GifsResource;
+    readonly workout: WorkoutResource;
+    readonly supplements: SupplementsResource;
+    readonly scan: ScanResource;
+    readonly auth: AuthResource;
+    readonly billing: BillingResource;
+    private readonly http;
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private cachedToken?;
+    private loginInFlight?;
+    private readonly scanAuth?;
+    constructor(opts?: WorkoutXOptions);
+    /** Build a direct GIF URL with the API key baked into the query string. */
+    gifUrl(filename: string): string;
+    /** Manually set/replace the body-scan Bearer token. */
+    setScanToken(token: string): void;
+    /** Resolve a Bearer token, logging in with email/password if needed. */
+    private getBearerToken;
+}
+
+/**
+ * Error raised for any non-2xx response from the WorkoutX API.
+ *
+ * The original parsed body (when JSON) is preserved on `.body`, and common
+ * fields the API returns (`error`, `message`, `tip`, `docs`) are surfaced
+ * directly so callers don't have to dig.
+ */
+declare class WorkoutXError extends Error {
+    /** HTTP status code (e.g. 401, 404, 429, 503). */
+    readonly status: number;
+    /** Short error label from the API body, e.g. "Not Found". */
+    readonly code?: string;
+    /** Hint the API sometimes returns to help fix the request. */
+    readonly tip?: string;
+    /** Docs URL the API sometimes returns. */
+    readonly docs?: string;
+    /** Raw parsed response body (object when JSON, string otherwise). */
+    readonly body: unknown;
+    /** The request path that failed, e.g. "/v1/exercises/lunges". */
+    readonly path: string;
+    constructor(args: {
+        status: number;
+        path: string;
+        body: unknown;
+        message: string;
+        code?: string;
+        tip?: string;
+        docs?: string;
+    });
+    /** True for 429 (rate limit / quota). */
+    get isRateLimited(): boolean;
+    /** True for 401/403 (auth/plan problems). */
+    get isAuthError(): boolean;
+    /** True for 404. */
+    get isNotFound(): boolean;
+}
+/** Raised when a network/transport failure prevents getting any response. */
+declare class WorkoutXConnectionError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+export { type AlternativesParams, type ApiTimestamp, type AuthLoginResult, AuthResource, BillingResource, type CalorieEstimate, DEFAULT_BASE_URL, type Exercise, ExercisesResource, GifsResource, type JsonObject, type PageParams, type PaginatedList, type ScanAuth, ScanResource, type SearchParams, type Supplement, SupplementsResource, type WorkoutGenerateParams, type WorkoutProgramParams, WorkoutResource, WorkoutX, WorkoutXConnectionError, WorkoutXError, type WorkoutXOptions };