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

package/dist/index.d.cts

@@ -0,0 +1,569 @@
+type CandidateStatus = 'invited' | 'started' | 'completed' | 'cancelled' | 'error';
+type SessionStatus = 'pending' | 'provisioning' | 'active' | 'submitted' | 'completed' | 'failed' | 'expired';
+interface Assessment {
+    id: string;
+    object: 'assessment';
+    name: string;
+    description: string | null;
+    challengeCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Candidate {
+    id: string;
+    object: 'candidate';
+    email: string;
+    name: string | null;
+    assessmentId: string;
+    externalId: string | null;
+    status: CandidateStatus;
+    invitationUrl: string | null;
+    invitedAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    cancelledAt: string | null;
+    expiresAt: string | null;
+    latestSessionId: string | null;
+    score: number | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SessionSubmission {
+    language: string | null;
+    finalCode: string | null;
+    diff: string | null;
+    commitSha: string | null;
+    previewUrl: string | null;
+}
+interface SessionInsights {
+    aiUsagePercent: number | null;
+    testPassRate: number | null;
+    codeQuality: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+interface SessionFeedback {
+    notes: string | null;
+    problemSolvingScore: number | null;
+    codeQualityScore: number | null;
+}
+/**
+ * Typed activity counters surfaced from `session_analytics`. All counts are
+ * non-negative integers and default to `0` when no events have been recorded
+ * yet (`null` is never returned). Lets partner UIs render "candidate spent
+ * X minutes coding, ran tests Y times" without parsing the opaque `insights`
+ * JSON blob.
+ */
+interface SessionAnalytics {
+    editorEventCount: number;
+    runEventCount: number;
+    testEventCount: number;
+    aiEventCount: number;
+    pasteEventCount: number;
+    activeSeconds: number;
+    idleSeconds: number;
+    codingSeconds: number;
+}
+interface Session {
+    id: string;
+    object: 'session';
+    candidateId: string;
+    assessmentId: string;
+    status: SessionStatus;
+    attempt: number;
+    startedAt: string | null;
+    completedAt: string | null;
+    durationSeconds: number | null;
+    score: number | null;
+    passed: boolean | null;
+    /**
+     * Partner-readable HTML report URL. Click-through opens a server-rendered
+     * report page for the recruiter (no Langos login required). `null` when the
+     * session has no calculated score yet.
+     */
+    reportUrl: string | null;
+    submission: SessionSubmission | null;
+    /** Typed activity stats; companion to the opaque `insights` blob. */
+    analytics: SessionAnalytics;
+    insights: SessionInsights | null;
+    feedback: SessionFeedback | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Canonical Langos plan tiers. Mirrors the public pricing page at
+ * https://www.langos.io/#pricing — the source of truth lives in the server's
+ * `plan-features.json`. No aliases, no synonyms; if a partner sees an unknown
+ * value here it's a deploy mismatch, not a plan tier we forgot to add.
+ *
+ * Note: `mid_tier` is the canonical key. There is no `mid` shorthand.
+ */
+type PlanTier = 'free' | 'starter' | 'mid_tier' | 'growth' | 'custom';
+/**
+ * Account info for the Langos company that owns the calling integration.
+ * Returned by `client.account.retrieve()`.
+ */
+interface Account {
+    id: string;
+    object: 'account';
+    name: string;
+    /**
+     * Immutable, auto-assigned URL slug for this company. Stable across the
+     * company's lifetime; safe to embed in your UI/links. Server-generated on
+     * signup — partners cannot set it.
+     */
+    slug: string;
+    /**
+     * The company's current plan tier. One of `free | starter | mid_tier |
+     * growth | custom`. Use this to gate UI on `planCaps` rather than hardcoding
+     * tier strings.
+     */
+    planTier: PlanTier;
+    billingCycle: string;
+    status: string;
+    sessionsUsed: number;
+    /** `null` on unlimited plans (e.g. `custom`). */
+    sessionsLimit: number | null;
+    /** `null` on unlimited plans (e.g. `custom`). */
+    sessionsRemaining: number | null;
+    trialEndsAt: string | null;
+    /**
+     * Top-level feature flags derived from the plan-features matrix and runtime
+     * configuration. Each flag answers "can this account use feature X right now?"
+     *
+     *   - `webIdeEnabled`        — true when the plan includes the web IDE.
+     *   - `replayEnabled`        — true when the plan includes session replay.
+     *   - `aiAssistanceEnabled`  — true ONLY when the plan includes AI assistance
+     *     AND an Anthropic API key is configured for the company. (Tier alone
+     *     isn't enough; AI is gated by tier but inert without a key.)
+     */
+    features: AccountFeatures;
+    /**
+     * What the company's plan tier *includes*, mirrored from the public pricing
+     * page. Read-only — partners use this to render upgrade prompts (e.g. "your
+     * plan caps at 30 sessions/mo, upgrade for unlimited"). `null` when the
+     * company is on a legacy or unknown tier.
+     */
+    planCaps: PlanCaps | null;
+    integration: AccountIntegration;
+}
+/**
+ * Plan capability block, mirrored from `plan-features.json` on the server.
+ * The shape mirrors the public pricing page: render upgrade prompts from this
+ * rather than hardcoding plan limits in your UI.
+ */
+interface PlanCaps {
+    label: string;
+    priceMonthly: number | null;
+    /** Billing cadence. Currently always `'monthly'`. */
+    billing: 'monthly';
+    /** Display currency. Currently always `'USD'`. */
+    currency: 'USD';
+    /** Sessions per billing period. `null` on unlimited tiers. */
+    sessionLimit: number | null;
+    /** Library challenges available out of the box. `null` on unlimited tiers. */
+    readyMadeChallenges: number | null;
+    /** Max custom challenges the company can author. `null` on unlimited tiers. */
+    customChallengesMax: number | null;
+    /**
+     * Raw feature matrix from plan-features.json — keys like `web_ide`,
+     * `replay`, `ai_assistance`, `sso`, etc. Prefer the typed `Account.features`
+     * for the small set of flags surfaced at top level.
+     */
+    features: Record<string, boolean>;
+    support: string;
+    popular: boolean;
+    contactSales: boolean;
+}
+/**
+ * Top-level feature flags, derived from `plan_caps.features` plus runtime
+ * configuration (see `aiAssistanceEnabled`).
+ */
+interface AccountFeatures {
+    /** True when `plan_caps.features.web_ide` is true. */
+    webIdeEnabled: boolean;
+    /** True when `plan_caps.features.replay` is true. */
+    replayEnabled: boolean;
+    /**
+     * True only when `plan_caps.features.ai_assistance` is true AND an
+     * Anthropic API key is configured for the company. Without the key, AI is
+     * gated by tier but would be inert at runtime.
+     */
+    aiAssistanceEnabled: boolean;
+}
+interface AccountIntegration {
+    /**
+     * Which integration path issued the calling API key.
+     *
+     * - `"customer"` — this key was minted from the Langos dashboard and used
+     *   directly via this SDK.
+     * - `"ashby"` (or another ATS slug) — Langos was wired through your ATS
+     *   partner; the customer is operating Langos inside the partner's UI.
+     *
+     * Both paths surface the same `/v1/account` data and call the same API.
+     */
+    provider: string;
+    apiKeyPrefix: string;
+    scopes: string[];
+    rateLimitPerMinute: number | null;
+    webhookUrl: string | null;
+}
+interface WebhookEndpoint {
+    object: 'webhook_endpoint';
+    webhookUrl: string | null;
+    /**
+     * The `whsec_…` signing secret. Only returned once, immediately after a
+     * `rotateSigningSecret: true` call. Subsequent reads return `null`.
+     */
+    signingSecret: string | null;
+}
+interface WebhookEndpointParams {
+    /** Absolute http(s) URL, or `null` to disable outbound delivery. */
+    webhookUrl?: string | null;
+    /**
+     * Generate a fresh signing secret. The previous secret is overwritten
+     * and cannot be recovered — store the response value.
+     */
+    rotateSigningSecret?: boolean;
+}
+interface CandidateCreateParams {
+    email: string;
+    assessmentId: string;
+    name?: string;
+    externalId?: string;
+    expiresAt?: string | Date;
+    metadata?: Record<string, unknown>;
+}
+interface ListParams {
+    limit?: number;
+    cursor?: string;
+}
+interface CandidateListParams extends ListParams {
+    status?: CandidateStatus;
+    assessmentId?: string;
+}
+interface AssessmentListParams extends ListParams {
+}
+interface SessionListParams extends ListParams {
+}
+/**
+ * Per-call request options. Override SDK defaults (timeout, retries) for a
+ * single call, supply an `AbortSignal`, or attach extra headers.
+ */
+interface RequestOptions {
+    timeout?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+}
+interface Logger {
+    debug(obj: object, msg?: string): void;
+    info(obj: object, msg?: string): void;
+    warn(obj: object, msg?: string): void;
+    error(obj: object, msg?: string): void;
+}
+interface LangosOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    logger?: Logger;
+    /** Free-form identifier appended to the User-Agent (e.g. "GreenhouseConnector/2.1.0"). */
+    appName?: string;
+    /** Disables outbound client telemetry header. */
+    telemetry?: boolean;
+}
+interface PageMeta {
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+interface Page<T> extends PageMeta {
+    data: T[];
+    /** Fetches the next page. Returns null when `hasMore` is false. */
+    getNextPage: () => Promise<Page<T> | null>;
+}
+type AsyncIterablePage<T> = AsyncIterable<T> & Page<T>;
+type WebhookEventType = 'session.submitted' | 'session.completed' | 'candidate.cancelled';
+/**
+ * Discriminated union of webhook event payloads. Each `type` narrows `data` to
+ * the corresponding shape so partners can `switch (event.type)` and let the
+ * compiler enforce exhaustive handling. When the server adds new event types,
+ * surface them here in lockstep.
+ */
+type Event = SessionSubmittedEvent | SessionCompletedEvent | CandidateCancelledEvent;
+interface BaseEvent<TType extends WebhookEventType, TData> {
+    id: string;
+    object: 'event';
+    type: TType;
+    created: string;
+    data: TData;
+}
+type SessionSubmittedEvent = BaseEvent<'session.submitted', Session>;
+type SessionCompletedEvent = BaseEvent<'session.completed', Session>;
+type CandidateCancelledEvent = BaseEvent<'candidate.cancelled', Candidate>;
+interface WebhookEvent<T = unknown> {
+    id: string;
+    object: 'event';
+    type: WebhookEventType;
+    created: string;
+    data: T;
+}
+
+interface ResolvedClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    fetchImpl: typeof fetch;
+    logger: Logger;
+    appName: string | undefined;
+    telemetry: boolean;
+}
+
+declare class APIResource {
+    protected readonly cfg: ResolvedClientConfig;
+    constructor(cfg: ResolvedClientConfig);
+    protected get<T>(path: string, query?: Record<string, string | number | undefined | null>, options?: RequestOptions): Promise<T>;
+    protected post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    protected delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    protected patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * `client.account` — read the company info that owns this integration, and
+ * manage the outbound webhook endpoint.
+ *
+ *  Typical usage:
+ *
+ *  ```ts
+ *  const account = await client.account.retrieve();
+ *  if (account.sessionsRemaining === 0) {
+ *    showUpgradePrompt();
+ *  }
+ *
+ *  await client.account.setWebhookEndpoint({
+ *    webhookUrl: 'https://greenhouse.example.com/webhooks/langos',
+ *    rotateSigningSecret: true,
+ *  });
+ *  ```
+ */
+declare class AccountResource extends APIResource {
+    /**
+     * Read the calling integration's account.
+     *
+     *  Includes plan, quota, feature flags, and integration metadata
+     *  (key prefix, scopes, rate limit, webhook URL).
+     *
+     * @returns {Promise<Account>}
+     */
+    retrieve(options?: RequestOptions): Promise<Account>;
+    /**
+     * Set or clear the outbound webhook URL, and optionally rotate the signing
+     * secret.
+     *
+     *  When `rotateSigningSecret: true`, the response includes the new secret in
+     *  `signingSecret`. Store it — the secret cannot be re-fetched. Subsequent
+     *  reads return `signingSecret: null`.
+     *
+     * @param {WebhookEndpointParams} params
+     */
+    setWebhookEndpoint(params: WebhookEndpointParams, options?: RequestOptions): Promise<WebhookEndpoint>;
+}
+
+declare class AssessmentsResource extends APIResource {
+    list(params?: AssessmentListParams, options?: RequestOptions): Promise<AsyncIterablePage<Assessment>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Assessment>;
+}
+
+declare class CandidatesResource extends APIResource {
+    list(params?: CandidateListParams, options?: RequestOptions): Promise<AsyncIterablePage<Candidate>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Candidate>;
+    create(params: CandidateCreateParams, options?: RequestOptions): Promise<Candidate>;
+    /** Idempotent — calling twice on a cancelled candidate returns the same record. */
+    cancel(id: string, options?: RequestOptions): Promise<Candidate>;
+}
+
+declare class SessionsResource extends APIResource {
+    retrieve(id: string, options?: RequestOptions): Promise<Session>;
+    listForCandidate(candidateId: string, params?: SessionListParams, options?: RequestOptions): Promise<AsyncIterablePage<Session>>;
+}
+
+declare class Langos {
+    readonly account: AccountResource;
+    readonly assessments: AssessmentsResource;
+    readonly candidates: CandidatesResource;
+    readonly sessions: SessionsResource;
+    /**
+     * Webhook signature helpers (`Langos.webhooks.constructEvent`). Static-style:
+     * does not need the client instance, since signing is independent of API
+     * calls. Exposed both as a class member and as `Langos.webhooks` for parity
+     * with Stripe's `stripe.webhooks` style.
+     */
+    readonly webhooks: {
+        constructEvent<T = unknown>(payload: string | Buffer, signatureHeader: string | string[] | undefined | null, secret: string, tolerance?: number): WebhookEvent<T>;
+    };
+    static readonly webhooks: {
+        constructEvent<T = unknown>(payload: string | Buffer, signatureHeader: string | string[] | undefined | null, secret: string, tolerance?: number): WebhookEvent<T>;
+    };
+    private readonly cfg;
+    constructor(options: LangosOptions);
+}
+
+/**
+ * Structured details merged into the 402 `quota_exceeded` error body. The
+ * server emits these as top-level fields alongside the standard problem+json
+ * envelope; partners can render an upgrade prompt without parsing free-form
+ * text.
+ */
+interface QuotaExceededDetails {
+    sessions_used: number;
+    sessions_limit: number;
+    /** ISO timestamp when the quota window resets. */
+    reset_at: string;
+    /** Absolute URL to the upgrade page; `null` if the server can't build one. */
+    upgrade_url: string | null;
+    /** The plan tier that hit the cap (e.g. `mid_tier`, `growth`). */
+    plan_tier: string;
+}
+/**
+ * Structured details merged into the 403 `feature_not_available` error body.
+ * Returned when an integration calls a feature its plan tier does not include
+ * (e.g. asking for replay on `starter`).
+ */
+interface FeatureNotAvailableDetails {
+    /** The plan-features key that is gated off (e.g. `replay`, `ai_assistance`). */
+    feature: string;
+    /** Absolute URL to the upgrade page; `null` if the server can't build one. */
+    upgrade_url: string | null;
+}
+interface LangosErrorBody {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    code?: string;
+    request_id?: string;
+    errors?: Array<{
+        field: string;
+        message: string;
+        code?: string;
+    }>;
+    [extra: string]: unknown;
+}
+declare class LangosError extends Error {
+    constructor(message: string);
+}
+/** Thrown when an HTTP response is received and indicates an error (>= 400). */
+declare class LangosAPIError extends LangosError {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly requestId: string | undefined;
+    readonly headers: Headers;
+    readonly body: LangosErrorBody | undefined;
+    readonly errors: LangosErrorBody['errors'] | undefined;
+    constructor(status: number, body: LangosErrorBody | undefined, headers: Headers, fallbackMessage: string);
+    /**
+     * Typed accessor for 402 `quota_exceeded` errors. Returns the structured
+     * details payload (sessions used/limit, reset timestamp, upgrade URL, plan
+     * tier) when the error matches; otherwise `null`.
+     *
+     * Use this instead of reaching into `err.body` to render upgrade prompts.
+     */
+    get quotaDetails(): QuotaExceededDetails | null;
+    /**
+     * Typed accessor for 403 `feature_not_available` errors. Returns the gated
+     * feature key and an upgrade URL; otherwise `null`.
+     */
+    get featureDetails(): FeatureNotAvailableDetails | null;
+    static from(status: number, body: unknown, headers: Headers): LangosAPIError;
+}
+declare const LangosAuthenticationError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosAuthenticationError = LangosAPIError;
+declare const LangosForbiddenError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosForbiddenError = LangosAPIError;
+declare const LangosNotFoundError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosNotFoundError = LangosAPIError;
+declare const LangosBadRequestError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosBadRequestError = LangosAPIError;
+declare const LangosConflictError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosConflictError = LangosAPIError;
+declare const LangosServerError: {
+    new (...args: any[]): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+} & typeof LangosAPIError;
+type LangosServerError = LangosAPIError;
+declare class LangosRateLimitError extends LangosAPIError {
+    readonly retryAfter: number | undefined;
+    constructor(status: number, body: LangosErrorBody | undefined, headers: Headers, fallback: string, retryAfter: number | undefined);
+}
+/** Thrown when the underlying fetch fails (DNS, TCP, TLS). */
+declare class LangosConnectionError extends LangosError {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/** Thrown when a request exceeds the configured timeout. */
+declare class LangosTimeoutError extends LangosError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** Thrown by `Langos.webhooks.constructEvent` when signature verification fails. */
+declare class LangosSignatureVerificationError extends LangosError {
+    constructor(reason: string);
+}
+
+/**
+ * Webhook helpers. v1.0 ships verification only — outbound delivery from Langos
+ * is on the roadmap. Partners can wire `constructEvent` against the planned
+ * signature header today; the SDK contract will not change when delivery lands.
+ *
+ * Pattern matches Stripe's `stripe.webhooks.constructEvent` so partners with
+ * existing handlers re-use the same shape.
+ */
+declare const Webhooks: {
+    constructEvent<T = unknown>(payload: string | Buffer, signatureHeader: string | string[] | undefined | null, secret: string, tolerance?: number): WebhookEvent<T>;
+};
+
+declare const version = "0.2.0-alpha.1";
+
+export { type Account, type AccountFeatures, type AccountIntegration, type Assessment, type AssessmentListParams, type AsyncIterablePage, type Candidate, type CandidateCancelledEvent, type CandidateCreateParams, type CandidateListParams, type CandidateStatus, type Event, type FeatureNotAvailableDetails, Langos, LangosAPIError, LangosAuthenticationError, LangosBadRequestError, LangosConflictError, LangosConnectionError, LangosError, type LangosErrorBody, LangosForbiddenError, LangosNotFoundError, type LangosOptions, LangosRateLimitError, LangosServerError, LangosSignatureVerificationError, LangosTimeoutError, type Logger, type Page, type PageMeta, type PlanCaps, type PlanTier, type QuotaExceededDetails, type RequestOptions, type Session, type SessionAnalytics, type SessionCompletedEvent, type SessionFeedback, type SessionInsights, type SessionListParams, type SessionStatus, type SessionSubmission, type SessionSubmittedEvent, type WebhookEndpoint, type WebhookEndpointParams, type WebhookEvent, type WebhookEventType, Webhooks, version };