@datacline/langos-sdk-node 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Security
+- **Webhook empty / short signing secret rejected.** `Webhooks.constructEvent` now requires `secret` to be a non-empty string of at least 16 characters. Prevents a forgery path where a partner who forgot to set `LANGOS_WEBHOOK_SECRET` would silently HMAC events against the empty string, allowing an attacker who knows this default to forge events that pass verification.
+- **Webhook timestamp parser hardened.** The `t=` value in the `Langos-Signature` header is now rejected if it is non-positive, NaN, or larger than `2**32` seconds (past the unix-epoch overflow boundary). Previously `t=0` and `t=-1` parsed as valid integers and only failed via the tolerance check, which is a fail-late posture for a malformed-input class.
+- **Header injection guard on `appName` and `apiKey`.** The `Langos` constructor now rejects strings containing `\r`, `\n`, `\0`, or any C0 control character. These would otherwise let an attacker who controls the partner's `appName` env splice arbitrary headers into every outbound request via the `User-Agent` line. Same guard applies to `apiKey` for the `Authorization` header.
+
+### Fixed
+- **`WebhookEventType` aligned with server-side publishers.** The union now matches the canonical set emitted by the server (`session.submitted`, `session.completed`, `candidate.cancelled`). The previous test fixture referenced a fictional `candidate.completed` event; that has been corrected. Also adds an `Event` discriminated union so partners can `switch (event.type)` and let the compiler enforce exhaustive handling.
+- **`409 Conflict` no longer auto-retried.** 409 is non-idempotent (duplicate email, version conflict, race against a parallel mutation) — retrying just burns the partner's rate-limit budget and amplifies the conflict. Partners should surface 409 to their caller and resolve the conflict explicitly.
+- **`WebhookEvent.created` matches the server's wire field.** The webhook envelope's timestamp field was typed as `createdAt`, but the server-side publisher emits `created`. Reading `event.createdAt` returned `undefined` at runtime while the type system claimed it was a string. Renamed to `created` on `WebhookEvent` and `BaseEvent` to remove the lie; partners using `event.created` get the real timestamp.
+
+## [0.2.0-alpha.1] - 2026-05-08
+
+### Added
+- **Customer Partner API SDK** — official Node.js / TypeScript client for the Langos Partner API (`@datacline/langos-sdk-node`)
+- **Assessment resource** — list published assessments, retrieve by id
+- **Challenge resource** — list coding challenges, retrieve by id
+- **Candidate resource** — invite candidates to assessments, list, retrieve, cancel invitations
+- **Session resource** — retrieve scoring results, analytics, and recruiter reports
+- **Account resource** — retrieve workspace plan tier, session quota, feature flags, and webhook configuration
+- **Webhook support** — register webhook endpoints, set signing secrets, validate inbound webhook signatures with `Langos.webhooks.constructEvent`
+- **Pagination** — async iterable cursor-based pagination on all list endpoints
+- **Error handling** — typed error classes: `LangosAPIError`, `LangosAuthenticationError`, `LangosForbiddenError`, `LangosNotFoundError`, `LangosBadRequestError`, `LangosRateLimitError`, `LangosServerError`, `LangosConnectionError`, `LangosTimeoutError`
+- **Automatic retries** — configurable exponential backoff with jitter on 5xx and `408`/`409`/`429` (max 2 retries by default)
+- **Idempotency** — automatic `Idempotency-Key` header generation for safe POST/PATCH/DELETE/PUT, honors `Retry-After` headers
+- **Zero runtime dependencies** — uses only Node.js built-ins (`fetch`, `crypto`)
+- **Dual module distribution** — ESM (`.mjs`), CommonJS (`.cjs`), and TypeScript declaration files (`.d.ts`)
+- **TypeScript first** — full type safety for all resources, error classes, and webhook events
+- **Webhook signature verification** — HMAC-SHA256 validation with static `Langos.webhooks.constructEvent` helper
+
+### Configuration
+- `apiKey` — required Bearer token for authentication
+- `baseUrl` — override default (production) endpoint for staging / self-hosted deploys
+- `timeout` — request timeout in milliseconds (default: 30,000)
+- `maxRetries` — max retry attempts on retryable errors (default: 2)
+- `appName` — optional app name appended to User-Agent
+- `logger` — optional Pino-shaped logger for debugging
+- `telemetry` — opt out of `X-Langos-Client-Telemetry` header (default: enabled)
+- `fetch` — optional custom fetch implementation for advanced use cases (e.g., custom proxies)
+
+### Documentation
+- Full integration guide in [CLAUDE.md](./CLAUDE.md) for SDK consumers and contributors
+- API reference in [README.md](./README.md) covering quickstart, auth, resources, pagination, errors, webhooks
+- Contributing guide in [CONTRIBUTING.md](./CONTRIBUTING.md) with testing and PR submission requirements
+
+### Known Limitations
+- Alpha release — surface is small and may change before `1.0.0`
+- Webhook delivery from Langos is on the v1.x roadmap; verification helper ships now so integrators can wire handlers ahead of GA
+
+### Development
+- **Testing** — unit tests with Vitest (~46 tests, no network dependency)
+- **Linting** — TypeScript strict mode with `tsc --noEmit`
+- **Build** — dual ESM+CJS build with tsup
+- **Package content** — validated tarball contents with `npm pack --dry-run`
+- **CI/CD** — GitHub Actions workflow testing Node 18.17, 20, and 22

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datacline Limited
+
+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,190 @@
+# `@datacline/langos-sdk-node`
+
+Official Node.js / TypeScript SDK for the Langos Partner API.
+
+This SDK is for ATS partners (Greenhouse, Lever, Ashby, custom in-house ATSs) embedding Langos coding assessments into their hiring workflow. It wraps the public Partner API at `app.langos.io/api/v1`.
+
+> **Status:** alpha. Surface is small (assessments, candidates, sessions, webhook signature verification) and may change before `1.0.0`.
+
+## Install
+
+```bash
+npm install @datacline/langos-sdk-node
+# or
+pnpm add @datacline/langos-sdk-node
+# or
+yarn add @datacline/langos-sdk-node
+```
+
+Requires **Node 18.17+** (Node 20 LTS recommended). Works in Bun, Deno (via npm:), Cloudflare Workers, and Vercel Edge as long as `fetch` and `crypto` are available.
+
+## Quickstart
+
+```ts
+import { Langos } from '@datacline/langos-sdk-node';
+
+const client = new Langos({ apiKey: process.env.LANGOS_API_KEY! });
+
+// 1. Find an assessment to invite a candidate to.
+for await (const a of await client.assessments.list()) {
+  console.log(a.id, a.name);
+}
+
+// 2. Invite a candidate.
+const candidate = await client.candidates.create({
+  email: 'jane@example.com',
+  name: 'Jane Doe',
+  assessmentId: 'asm_abc',
+  externalId: 'greenhouse-app-12345',
+});
+console.log('Invitation URL:', candidate.invitationUrl);
+
+// 3. Poll for results (or use webhooks once outbound delivery ships).
+const fresh = await client.candidates.retrieve(candidate.id);
+if (fresh.status === 'completed' && fresh.latestSessionId) {
+  const session = await client.sessions.retrieve(fresh.latestSessionId);
+  console.log('Score:', session.score);
+}
+```
+
+## Authentication
+
+Set `Authorization: Bearer <api_key>`. The SDK does this for you — just pass `apiKey` to the constructor. API keys are issued by the Langos workspace owner via the recruiter dashboard.
+
+## Other integration paths
+
+Langos integrates with ATS platforms directly (Ashby today; more coming). If your team uses Ashby, you can connect Langos via the Ashby App Marketplace instead of this SDK — both paths surface the same `/v1/account` data, but Ashby manages auth on your behalf. Use this SDK when you want a direct API integration; use the Ashby flow when you'd rather operate Langos inside Ashby's UI.
+
+The `account.integration.provider` field tells you which path your key is using:
+- `'customer'` — you minted this key from the Langos dashboard (this SDK)
+- `'ashby'` (or another ATS slug) — Langos was wired through your ATS partner
+
+## Resources
+
+| Resource | Methods |
+|---|---|
+| `client.assessments` | `list`, `retrieve` |
+| `client.candidates` | `list`, `retrieve`, `create`, `cancel` |
+| `client.sessions` | `retrieve`, `listForCandidate` |
+| `Langos.webhooks` | `constructEvent` (signature verification) |
+
+## Pagination
+
+List methods return an `AsyncIterablePage`. Either iterate across pages automatically:
+
+```ts
+for await (const c of await client.candidates.list({ status: 'completed' })) {
+  console.log(c.email);
+}
+```
+
+Or page manually:
+
+```ts
+const page = await client.candidates.list({ limit: 50 });
+console.log(page.data, page.hasMore, page.nextCursor);
+const next = await page.getNextPage(); // null when hasMore is false
+```
+
+## Error handling
+
+All API errors throw a typed subclass of `LangosError`:
+
+```ts
+import {
+  LangosAPIError,
+  LangosAuthenticationError,
+  LangosForbiddenError,
+  LangosNotFoundError,
+  LangosBadRequestError,
+  LangosRateLimitError,
+  LangosServerError,
+  LangosConnectionError,
+  LangosTimeoutError,
+} from '@datacline/langos-sdk-node';
+
+try {
+  await client.candidates.create({ email: 'x@y.com', assessmentId: 'asm_abc' });
+} catch (err) {
+  if (err instanceof LangosRateLimitError) {
+    await sleep((err.retryAfter ?? 1) * 1000);
+    // retry
+  } else if (err instanceof LangosBadRequestError) {
+    console.warn('field errors:', err.errors); // [{ field, message, code }]
+  } else if (err instanceof LangosAPIError) {
+    console.error(err.status, err.code, err.requestId);
+    // Include err.requestId when reporting bugs to Langos support.
+  } else throw err;
+}
+```
+
+## Retries & idempotency
+
+The SDK retries on connection errors and `408`/`409`/`429`/`5xx` (except `501`) up to `maxRetries: 2` by default, with exponential backoff and jitter, honoring `Retry-After`.
+
+For unsafe methods (`POST`, `PATCH`, `DELETE`, `PUT`), an `Idempotency-Key` header is auto-generated and reused across retries — duplicate side effects are eliminated. Override with your own:
+
+```ts
+await client.candidates.create(
+  { email: 'x@y.com', assessmentId: 'asm_abc' },
+  { idempotencyKey: 'greenhouse-app-12345-v1' },
+);
+```
+
+## Webhook signature verification
+
+Verify incoming Langos webhooks with the static helper:
+
+```ts
+import express from 'express';
+import { Langos } from '@datacline/langos-sdk-node';
+
+const app = express();
+
+app.post(
+  '/webhooks/langos',
+  express.raw({ type: 'application/json' }),  // CRITICAL: raw body required
+  (req, res) => {
+    try {
+      const event = Langos.webhooks.constructEvent(
+        req.body,
+        req.headers['langos-signature'],
+        process.env.LANGOS_WEBHOOK_SECRET!,
+      );
+      console.log(event.type, event.data);
+      res.status(204).end();
+    } catch {
+      res.status(400).send('invalid signature');
+    }
+  },
+);
+```
+
+> **Important:** pass the **raw body**, not the parsed JSON. `express.json()` will reformat keys/whitespace and break signature verification.
+
+> **Note:** Outbound webhook delivery from Langos is on the v1.x roadmap. The verification helper ships now so you can wire your handler ahead of GA without an SDK upgrade later.
+
+## Configuration
+
+```ts
+const client = new Langos({
+  apiKey: process.env.LANGOS_API_KEY!,
+  baseUrl: 'https://app.langos.io/api/v1',  // override for self-host / staging
+  timeout: 30_000,                           // ms
+  maxRetries: 2,
+  appName: 'GreenhouseConnector/2.1.0',     // appended to User-Agent
+  logger: pino(),                            // optional Pino-shaped logger
+  telemetry: false,                          // opt out of X-Langos-Client-Telemetry
+  fetch: customFetch,                        // inject custom fetch
+});
+```
+
+Per-call overrides via `RequestOptions`:
+
+```ts
+await client.assessments.list({}, { timeout: 60_000, maxRetries: 5, signal: ac.signal });
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE)