@lagapp/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@lagapp/sdk` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-10
+
+### Added
+- Initial release covering the public REST surface of the Lag API.
+- `LagClient` with resources: `system`, `users`, `friends`, `dms`, `servers`, `events`, `images`.
+- Sub-resources: server `invites`, `members`, `roles`, `rooms`, room `messages`, event `guests`, event `templates`.
+- Cursor-based pagination helpers with `AsyncIterable` page walking.
+- Typed error hierarchy: `LagApiError`, `LagAuthError`, `LagPermissionError`, `LagNotFoundError`, `LagConflictError`, `LagRateLimitError`, `LagServerError`, `LagConnectionError`.
+- Automatic retries with exponential backoff and `Retry-After` support.
+- Multipart image upload from path, `Buffer`, `Uint8Array`, `Blob`, or `ReadableStream`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lag
+
+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,207 @@
+# @lagapp/sdk
+
+The official TypeScript / Node SDK for the [Lag](https://trylag.com) API.
+
+`@lagapp/sdk` is a small, hand-written REST client for the public Lag API. It
+covers users, friends, DMs, servers, rooms, room messages, events, and image
+uploads. It does **not** include the WebSocket protocol or the voice client -
+those are out of scope for this package.
+
+- Zero runtime dependencies (uses the global `fetch` from Node 18+).
+- ESM, ships `.d.ts` declarations.
+- Typed error hierarchy with automatic retries on transient failures.
+- Cursor pagination with an async-iterable helper for walking pages.
+
+## Install
+
+```bash
+npm install @lagapp/sdk
+# or
+pnpm add @lagapp/sdk
+# or
+yarn add @lagapp/sdk
+```
+
+## Quickstart
+
+```ts
+import { LagClient } from '@lagapp/sdk';
+
+const client = new LagClient({
+  token: process.env.LAG_TOKEN!, // a Personal Access Token (lag_pat_*) or Supabase JWT
+});
+
+const me = await client.users.me();
+console.log(`Hello, ${me.displayName ?? me.username}`);
+
+const servers = await client.servers.list();
+for (const server of servers) {
+  console.log(`- ${server.name} (${server.memberCount} members)`);
+}
+```
+
+## Authentication
+
+The SDK accepts any Bearer token the API would accept:
+
+- A **Personal Access Token** (`lag_pat_*`) - the recommended option for
+  scripts, bots, and CI. Create one in the Lag web app under settings, or via
+  the `lag` CLI with `lag auth login`.
+- A **Supabase JWT** - useful when you already have an authenticated session,
+  e.g. inside a SvelteKit server load function.
+
+The token is sent as `Authorization: Bearer <token>` on every request. The SDK
+does not implement OAuth flows, refresh tokens, or browser-based login - if
+you need any of those, obtain a token elsewhere and pass it in.
+
+## Configuration
+
+```ts
+const client = new LagClient({
+  token: 'lag_pat_...',
+  baseUrl: 'https://api.trylag.com', // default
+  timeoutMs: 30_000,                  // default
+  maxRetries: 2,                       // default
+  userAgent: 'my-app/1.0',             // optional override
+  fetch: customFetch,                  // optional fetch implementation
+});
+```
+
+`maxRetries` controls how many times the client will retry on a transient
+failure (5xx, 429, network error). Backoff is exponential with jitter, capped
+at ~8s. The server's `Retry-After` header is honored on 429.
+
+## Resources
+
+Every resource hangs off the `LagClient` instance:
+
+| Property | What it covers |
+|---|---|
+| `client.system` | `/health`, `/version`, `/system-status`, `/config` |
+| `client.users` | `/users/me`, `/users/me/avatar`, `/users/:id`, `/users/search`, `/users/check-username`, Steam helpers |
+| `client.friends` | List, requests, send/accept/decline, remove, block |
+| `client.dms` | Conversations + messages with cursor pagination |
+| `client.servers` | Servers CRUD, icon upload, leave |
+| `client.servers.invites` | Create / list / revoke / preview / join |
+| `client.servers.members` | Kick, ban, mute (and the corresponding lists) |
+| `client.servers.roles` | Role CRUD and assignment |
+| `client.servers.rooms` | Voice rooms |
+| `client.servers.rooms.messages` | Room chat: list/send/edit/delete with cursor pagination |
+| `client.events` | Server events: list/create/get/update/cancel/RSVP |
+| `client.events.guests` | Host-side guest moderation |
+| `client.events.templates` | Recurring event templates |
+| `client.images` | Multipart upload, metadata, status, delete |
+
+### Pagination
+
+DM and room message endpoints return:
+
+```ts
+{ messages: [...], hasMore: boolean, nextCursor: string | null }
+```
+
+You can call them by hand:
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await client.dms.listMessages(convId, { limit: 50, cursor });
+  for (const msg of page.messages) handle(msg);
+  cursor = page.nextCursor ?? undefined;
+} while (cursor);
+```
+
+Or async-iterate them with the built-in walker:
+
+```ts
+for await (const page of client.dms.iterMessages(convId, { limit: 50 })) {
+  for (const msg of page.items) handle(msg);
+}
+```
+
+The same pattern works for room messages via
+`client.servers.rooms.messages.iter(serverId, roomId)`.
+
+### Image upload
+
+```ts
+import { readFileSync } from 'node:fs';
+import { LagClient } from '@lagapp/sdk';
+
+const client = new LagClient({ token: process.env.LAG_TOKEN! });
+
+// From a file path:
+await client.images.upload('./avatar.png', { purpose: 'avatar' });
+
+// From raw bytes:
+const bytes = readFileSync('./avatar.png');
+await client.images.upload(bytes, {
+  purpose: 'avatar',
+  filename: 'avatar.png',
+  contentType: 'image/png',
+});
+
+// From a Blob (works in browsers and Node 18+):
+const blob = new Blob([bytes], { type: 'image/png' });
+await client.images.upload(blob, { purpose: 'general' });
+```
+
+The SDK builds the multipart request itself; you do not need to construct
+`FormData`. Maximum upload size is 25 MiB.
+
+## Error handling
+
+Every non-2xx response becomes a typed error you can match with `instanceof`:
+
+```ts
+import {
+  LagApiError,
+  LagAuthError,
+  LagPermissionError,
+  LagNotFoundError,
+  LagConflictError,
+  LagRateLimitError,
+  LagServerError,
+  LagConnectionError,
+} from '@lagapp/sdk';
+
+try {
+  await client.servers.get('does-not-exist');
+} catch (err) {
+  if (err instanceof LagNotFoundError) {
+    // 404
+  } else if (err instanceof LagRateLimitError) {
+    // 429 - err.retryAfterSeconds may contain the server's hint
+  } else if (err instanceof LagApiError) {
+    // any other API error
+    console.error(err.status, err.message, err.body);
+  } else {
+    throw err;
+  }
+}
+```
+
+Network failures (DNS, refused connection, timeouts before any response)
+throw `LagConnectionError`. Everything else is a subclass of `LagApiError`.
+
+## Local development
+
+```bash
+npm install
+npm run build       # tsc -> dist/
+npm run typecheck
+npm test            # node --test via tsx
+```
+
+Tests run against an in-process HTTP server (`test/helpers/mock-server.ts`)
+so no real Lag API is required. Each resource has its own test file.
+
+## Related
+
+- The Lag API itself - source under `product/apps/api/` in the Lag monorepo.
+- `lag-sdk` for Python (sibling package in `sdks/python/`).
+- The `lag` CLI - `cli/` in the Lag monorepo, MIT licensed.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import { type LagClientOptions } from './http.js';
+import { SystemResource } from './resources/system.js';
+import { UsersResource } from './resources/users.js';
+import { FriendsResource } from './resources/friends.js';
+import { DmsResource } from './resources/dms.js';
+import { ServersResource } from './resources/servers.js';
+import { EventsResource } from './resources/events.js';
+import { ImagesResource } from './resources/images.js';
+/**
+ * The Lag SDK entry point.
+ *
+ * Construct it with a bearer token (a Personal Access Token, format
+ * `lag_pat_*`, or a Supabase JWT) and access resources off the instance:
+ *
+ *   ```ts
+ *   import { LagClient } from '@lagapp/sdk';
+ *
+ *   const client = new LagClient({ token: process.env.LAG_TOKEN! });
+ *   const me = await client.users.me();
+ *   const servers = await client.servers.list();
+ *   ```
+ *
+ * The client is stateless beyond the underlying fetch implementation, so a
+ * single instance is safe to share across requests / workers.
+ */
+export declare class LagClient {
+    readonly system: SystemResource;
+    readonly users: UsersResource;
+    readonly friends: FriendsResource;
+    readonly dms: DmsResource;
+    readonly servers: ServersResource;
+    readonly events: EventsResource;
+    readonly images: ImagesResource;
+    constructor(options: LagClientOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;IACpB,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,SAAgB,KAAK,EAAE,aAAa,CAAC;IACrC,SAAgB,OAAO,EAAE,eAAe,CAAC;IACzC,SAAgB,GAAG,EAAE,WAAW,CAAC;IACjC,SAAgB,OAAO,EAAE,eAAe,CAAC;IACzC,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,SAAgB,MAAM,EAAE,cAAc,CAAC;gBAE3B,OAAO,EAAE,gBAAgB;CAUtC"}

package/dist/client.js

@@ -0,0 +1,45 @@
+import { HttpClient } from './http.js';
+import { SystemResource } from './resources/system.js';
+import { UsersResource } from './resources/users.js';
+import { FriendsResource } from './resources/friends.js';
+import { DmsResource } from './resources/dms.js';
+import { ServersResource } from './resources/servers.js';
+import { EventsResource } from './resources/events.js';
+import { ImagesResource } from './resources/images.js';
+/**
+ * The Lag SDK entry point.
+ *
+ * Construct it with a bearer token (a Personal Access Token, format
+ * `lag_pat_*`, or a Supabase JWT) and access resources off the instance:
+ *
+ *   ```ts
+ *   import { LagClient } from '@lagapp/sdk';
+ *
+ *   const client = new LagClient({ token: process.env.LAG_TOKEN! });
+ *   const me = await client.users.me();
+ *   const servers = await client.servers.list();
+ *   ```
+ *
+ * The client is stateless beyond the underlying fetch implementation, so a
+ * single instance is safe to share across requests / workers.
+ */
+export class LagClient {
+    system;
+    users;
+    friends;
+    dms;
+    servers;
+    events;
+    images;
+    constructor(options) {
+        const http = new HttpClient(options);
+        this.system = new SystemResource(http);
+        this.users = new UsersResource(http);
+        this.friends = new FriendsResource(http);
+        this.dms = new DmsResource(http);
+        this.servers = new ServersResource(http);
+        this.events = new EventsResource(http);
+        this.images = new ImagesResource(http);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAyB,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,SAAS;IACJ,MAAM,CAAiB;IACvB,KAAK,CAAgB;IACrB,OAAO,CAAkB;IACzB,GAAG,CAAc;IACjB,OAAO,CAAkB;IACzB,MAAM,CAAiB;IACvB,MAAM,CAAiB;IAEvC,YAAY,OAAyB;QACnC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Error envelope returned by the Lag API.
+ *
+ * Every API error response has the shape `{ error, message, statusCode }`.
+ * The SDK parses these into a typed exception hierarchy so consumers can
+ * `instanceof`-match the failure cases they care about.
+ */
+export interface LagApiErrorBody {
+    error: string;
+    message: string;
+    statusCode: number;
+}
+/**
+ * Base class for every error thrown by the Lag SDK.
+ *
+ * Subclasses correspond to specific HTTP status codes:
+ *   - `LagAuthError`        - 401
+ *   - `LagPermissionError`  - 403
+ *   - `LagNotFoundError`    - 404
+ *   - `LagConflictError`    - 409
+ *   - `LagRateLimitError`   - 429
+ *   - `LagServerError`      - 5xx
+ *
+ * Network failures (DNS, connection refused, timeouts before any status was
+ * received) are wrapped in `LagConnectionError`.
+ */
+export declare class LagApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly body: LagApiErrorBody | null;
+    readonly requestId: string | null;
+    constructor(message: string, status: number, code: string, body: LagApiErrorBody | null, requestId: string | null);
+}
+export declare class LagAuthError extends LagApiError {
+    constructor(message: string, body: LagApiErrorBody | null, requestId: string | null);
+}
+export declare class LagPermissionError extends LagApiError {
+    constructor(message: string, body: LagApiErrorBody | null, requestId: string | null);
+}
+export declare class LagNotFoundError extends LagApiError {
+    constructor(message: string, body: LagApiErrorBody | null, requestId: string | null);
+}
+export declare class LagConflictError extends LagApiError {
+    constructor(message: string, body: LagApiErrorBody | null, requestId: string | null);
+}
+export declare class LagRateLimitError extends LagApiError {
+    /** Seconds the server asked the client to wait, parsed from `Retry-After`. */
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, body: LagApiErrorBody | null, requestId: string | null, retryAfterSeconds: number | null);
+}
+export declare class LagServerError extends LagApiError {
+    constructor(message: string, status: number, body: LagApiErrorBody | null, requestId: string | null);
+}
+/** Thrown when the request never reached the server (DNS, refused, timed out). */
+export declare class LagConnectionError extends LagApiError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Build the appropriate `LagApiError` subclass for an HTTP response.
+ *
+ * The Lag API always returns a JSON error envelope, but we still defend
+ * against truncated or non-JSON bodies (e.g. an upstream proxy returning
+ * plain text on 502).
+ */
+export declare function errorFromResponse(status: number, body: LagApiErrorBody | null, requestId: string | null, retryAfterSeconds: number | null): LagApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7C,SAAgB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,SAAS,EAAE,MAAM,GAAG,IAAI;CAS3B;AAED,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpF;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpF;AAED,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpF;AAED,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpF;AAED,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,8EAA8E;IAC9E,SAAgB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;gBAG/C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI;CAMnC;AAED,qBAAa,cAAe,SAAQ,WAAW;gBACjC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAIpG;AAED,kFAAkF;AAClF,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,SAAyB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAC7B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,GAAG,IAAI,EAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,WAAW,CAiBb"}

package/dist/errors.js

@@ -0,0 +1,103 @@
+/**
+ * Base class for every error thrown by the Lag SDK.
+ *
+ * Subclasses correspond to specific HTTP status codes:
+ *   - `LagAuthError`        - 401
+ *   - `LagPermissionError`  - 403
+ *   - `LagNotFoundError`    - 404
+ *   - `LagConflictError`    - 409
+ *   - `LagRateLimitError`   - 429
+ *   - `LagServerError`      - 5xx
+ *
+ * Network failures (DNS, connection refused, timeouts before any status was
+ * received) are wrapped in `LagConnectionError`.
+ */
+export class LagApiError extends Error {
+    status;
+    code;
+    body;
+    requestId;
+    constructor(message, status, code, body, requestId) {
+        super(message);
+        this.name = 'LagApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.requestId = requestId;
+    }
+}
+export class LagAuthError extends LagApiError {
+    constructor(message, body, requestId) {
+        super(message, 401, 'unauthorized', body, requestId);
+        this.name = 'LagAuthError';
+    }
+}
+export class LagPermissionError extends LagApiError {
+    constructor(message, body, requestId) {
+        super(message, 403, 'forbidden', body, requestId);
+        this.name = 'LagPermissionError';
+    }
+}
+export class LagNotFoundError extends LagApiError {
+    constructor(message, body, requestId) {
+        super(message, 404, 'not_found', body, requestId);
+        this.name = 'LagNotFoundError';
+    }
+}
+export class LagConflictError extends LagApiError {
+    constructor(message, body, requestId) {
+        super(message, 409, 'conflict', body, requestId);
+        this.name = 'LagConflictError';
+    }
+}
+export class LagRateLimitError extends LagApiError {
+    /** Seconds the server asked the client to wait, parsed from `Retry-After`. */
+    retryAfterSeconds;
+    constructor(message, body, requestId, retryAfterSeconds) {
+        super(message, 429, 'rate_limited', body, requestId);
+        this.name = 'LagRateLimitError';
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class LagServerError extends LagApiError {
+    constructor(message, status, body, requestId) {
+        super(message, status, 'server_error', body, requestId);
+        this.name = 'LagServerError';
+    }
+}
+/** Thrown when the request never reached the server (DNS, refused, timed out). */
+export class LagConnectionError extends LagApiError {
+    cause;
+    constructor(message, cause) {
+        super(message, 0, 'connection_error', null, null);
+        this.name = 'LagConnectionError';
+        this.cause = cause;
+    }
+}
+/**
+ * Build the appropriate `LagApiError` subclass for an HTTP response.
+ *
+ * The Lag API always returns a JSON error envelope, but we still defend
+ * against truncated or non-JSON bodies (e.g. an upstream proxy returning
+ * plain text on 502).
+ */
+export function errorFromResponse(status, body, requestId, retryAfterSeconds) {
+    const message = body?.message || `HTTP ${status}`;
+    switch (status) {
+        case 401:
+            return new LagAuthError(message, body, requestId);
+        case 403:
+            return new LagPermissionError(message, body, requestId);
+        case 404:
+            return new LagNotFoundError(message, body, requestId);
+        case 409:
+            return new LagConflictError(message, body, requestId);
+        case 429:
+            return new LagRateLimitError(message, body, requestId, retryAfterSeconds);
+        default:
+            if (status >= 500)
+                return new LagServerError(message, status, body, requestId);
+            return new LagApiError(message, status, body?.error ?? `http_${status}`, body, requestId);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,61 @@
+import { LagApiError } from './errors.js';
+export interface LagClientOptions {
+    /** Bearer token: a Personal Access Token (lag_pat_*) or Supabase JWT. */
+    token: string;
+    /** API base URL. Defaults to `https://api.trylag.com`. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 30000 (30s). */
+    timeoutMs?: number;
+    /** Maximum retry attempts for transient failures. Defaults to 2. */
+    maxRetries?: number;
+    /** Override the User-Agent string. */
+    userAgent?: string;
+    /** Custom fetch implementation (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    /** When true, body is sent raw (multipart) instead of JSON-encoded. */
+    rawBody?: BodyInit;
+    /** Extra headers merged onto the default set. */
+    headers?: Record<string, string>;
+    /** Override the client default timeout. */
+    timeoutMs?: number;
+    /** Override the client default retry count. */
+    maxRetries?: number;
+}
+/**
+ * Low-level HTTP transport shared by every resource.
+ *
+ * Responsibilities:
+ *   - Inject Authorization, User-Agent, Accept headers.
+ *   - Build query strings, JSON-encode bodies, parse JSON responses.
+ *   - Map non-2xx responses to typed errors.
+ *   - Retry transient failures (5xx, 429, network) with exponential backoff.
+ *   - Honor the server's `Retry-After` header on 429.
+ *   - Enforce per-request timeouts via AbortController.
+ */
+export declare class HttpClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    constructor(opts: LagClientOptions);
+    request<T>(opts: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    private buildBody;
+    private decodeBody;
+    private parseErrorBody;
+}
+/**
+ * Re-export so consumers can `instanceof`-check transport-layer errors
+ * without importing from a deeper path.
+ */
+export { LagApiError };
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EAIZ,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,gBAAgB;IAe5B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IA2DlD,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,SAAS;YAMH,UAAU;YAgBV,cAAc;CAkB7B;AAyBD;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,CAAC"}