wellmarked 1.1.0

package/dist/esm/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Exception hierarchy for the WellMarked SDK.
+ *
+ * Every HTTP error returned by the API is translated into a typed error
+ * whose class corresponds to the HTTP status and whose `code` matches the
+ * `error.code` field in the response body. Catch `WellMarkedError` for
+ * anything raised by the SDK; catch a more specific subclass when you want
+ * to handle one failure mode.
+ */
+export interface WellMarkedErrorOptions {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    retryAfter?: number | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+export declare class WellMarkedError extends Error {
+    readonly code: string | undefined;
+    readonly statusCode: number | undefined;
+    readonly retryAfter: number | undefined;
+    readonly requestId: string | undefined;
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** Raised when the SDK couldn't reach the API (DNS, TCP, TLS, timeout). */
+export declare class APIConnectionError extends WellMarkedError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** Raised for any non-2xx response from the API. */
+export declare class APIStatusError extends WellMarkedError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** 401 — missing or invalid API key. */
+export declare class AuthenticationError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** 403 — account inactive, plan does not allow this operation, or job belongs to another user. */
+export declare class PermissionDeniedError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** 404 — job not found or expired past the 6-hour retention window. */
+export declare class NotFoundError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/**
+ * 422 — request was syntactically valid but couldn't be fulfilled.
+ *
+ * Common `code` values:
+ *   - `no_content`            — could not identify main content on the page
+ *   - `target_timeout`        — the target URL timed out
+ *   - `js_rendering_disabled` — `renderJs=true` but the server has it off
+ *   - `bulk_cap_exceeded`     — more URLs than the plan allows per request
+ *   - `crawl_depth_exceeded`  — requested depth above the plan cap
+ */
+export declare class UnprocessableEntityError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** 429 — monthly plan limit reached. `retryAfter` is the number of seconds until reset. */
+export declare class RateLimitError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** 5xx — something went wrong on the API side. */
+export declare class InternalServerError extends APIStatusError {
+    constructor(message: string, options?: WellMarkedErrorOptions);
+}
+/** Build the right error subclass for a given HTTP status + JSON body. */
+export declare function fromResponse(statusCode: number, body: unknown, requestId?: string): APIStatusError;

package/dist/esm/errors.js

@@ -0,0 +1,130 @@
+/**
+ * Exception hierarchy for the WellMarked SDK.
+ *
+ * Every HTTP error returned by the API is translated into a typed error
+ * whose class corresponds to the HTTP status and whose `code` matches the
+ * `error.code` field in the response body. Catch `WellMarkedError` for
+ * anything raised by the SDK; catch a more specific subclass when you want
+ * to handle one failure mode.
+ */
+export class WellMarkedError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "WellMarkedError";
+        this.code = options.code;
+        this.statusCode = options.statusCode;
+        this.retryAfter = options.retryAfter;
+        this.requestId = options.requestId;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        // Maintain proper prototype chain when transpiled to ES5.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Raised when the SDK couldn't reach the API (DNS, TCP, TLS, timeout). */
+export class APIConnectionError extends WellMarkedError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "APIConnectionError";
+        Object.setPrototypeOf(this, APIConnectionError.prototype);
+    }
+}
+/** Raised for any non-2xx response from the API. */
+export class APIStatusError extends WellMarkedError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "APIStatusError";
+        Object.setPrototypeOf(this, APIStatusError.prototype);
+    }
+}
+/** 401 — missing or invalid API key. */
+export class AuthenticationError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "AuthenticationError";
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+/** 403 — account inactive, plan does not allow this operation, or job belongs to another user. */
+export class PermissionDeniedError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "PermissionDeniedError";
+        Object.setPrototypeOf(this, PermissionDeniedError.prototype);
+    }
+}
+/** 404 — job not found or expired past the 6-hour retention window. */
+export class NotFoundError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "NotFoundError";
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+/**
+ * 422 — request was syntactically valid but couldn't be fulfilled.
+ *
+ * Common `code` values:
+ *   - `no_content`            — could not identify main content on the page
+ *   - `target_timeout`        — the target URL timed out
+ *   - `js_rendering_disabled` — `renderJs=true` but the server has it off
+ *   - `bulk_cap_exceeded`     — more URLs than the plan allows per request
+ *   - `crawl_depth_exceeded`  — requested depth above the plan cap
+ */
+export class UnprocessableEntityError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "UnprocessableEntityError";
+        Object.setPrototypeOf(this, UnprocessableEntityError.prototype);
+    }
+}
+/** 429 — monthly plan limit reached. `retryAfter` is the number of seconds until reset. */
+export class RateLimitError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "RateLimitError";
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+/** 5xx — something went wrong on the API side. */
+export class InternalServerError extends APIStatusError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.name = "InternalServerError";
+        Object.setPrototypeOf(this, InternalServerError.prototype);
+    }
+}
+const STATUS_TO_EXC = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+};
+/** Build the right error subclass for a given HTTP status + JSON body. */
+export function fromResponse(statusCode, body, requestId) {
+    let code;
+    let message = `HTTP ${statusCode}`;
+    let retryAfter;
+    if (body && typeof body === "object" && "error" in body) {
+        const err = body.error;
+        if (err && typeof err === "object") {
+            const e = err;
+            if (typeof e.code === "string")
+                code = e.code;
+            if (typeof e.message === "string")
+                message = e.message;
+            if (typeof e.retry_after === "number")
+                retryAfter = e.retry_after;
+        }
+    }
+    let Ctor;
+    if (statusCode >= 500) {
+        Ctor = InternalServerError;
+    }
+    else {
+        Ctor = STATUS_TO_EXC[statusCode] ?? APIStatusError;
+    }
+    return new Ctor(message, { code, statusCode, retryAfter, requestId });
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Official JavaScript/TypeScript SDK for the WellMarked API.
+ *
+ *     import { WellMarked } from "wellmarked";
+ *
+ *     const wm = new WellMarked({ apiKey: "wm_..." });
+ *     const result = await wm.extract("https://example.com/article");
+ *     console.log(result.markdown);
+ *
+ * See https://wellmarked.io/docs for the full API reference.
+ */
+export { VERSION } from "./version.js";
+export { WellMarked, type WellMarkedOptions, type ExtractOptions, type BulkOptions, type CrawlOptions, type WaitForJobOptions, } from "./client.js";
+export { type BulkItem, type BulkJob, type CrawlItem, type CrawlJob, type ExtractionMeta, type ExtractResult, type JobStatus, type RotatedKey, type TruncatedReason, type Usage, isBulkJob, isCrawlJob, } from "./models.js";
+export { APIConnectionError, APIStatusError, AuthenticationError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, WellMarkedError, } from "./errors.js";

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+/**
+ * Official JavaScript/TypeScript SDK for the WellMarked API.
+ *
+ *     import { WellMarked } from "wellmarked";
+ *
+ *     const wm = new WellMarked({ apiKey: "wm_..." });
+ *     const result = await wm.extract("https://example.com/article");
+ *     console.log(result.markdown);
+ *
+ * See https://wellmarked.io/docs for the full API reference.
+ */
+export { VERSION } from "./version.js";
+export { WellMarked, } from "./client.js";
+export { isBulkJob, isCrawlJob, } from "./models.js";
+export { APIConnectionError, APIStatusError, AuthenticationError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, WellMarkedError, } from "./errors.js";

package/dist/esm/models.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed response objects returned by the WellMarked SDK.
+ *
+ * These mirror the JSON shapes documented at https://api.wellmarked.io/docs.
+ *
+ * Response objects carry only the body fields documented in the API
+ * reference — they do not surface HTTP headers. Quota state lives on the
+ * account, so use `WellMarked.getUsage()` to read it.
+ */
+/**
+ * Per-article metadata returned with each extraction.
+ *
+ * `date` is the article's published date as a string (often `null` — not
+ * every page publishes one). `retrievedAt` is the timestamp at which
+ * WellMarked actually fetched the page, populated on every successful
+ * extraction. The two fields are independent.
+ */
+export interface ExtractionMeta {
+    url: string;
+    title: string | null;
+    author: string | null;
+    date: string | null;
+    retrievedAt: Date | null;
+}
+export declare function extractionMetaFromDict(data: Record<string, unknown>): ExtractionMeta;
+/** Result of `POST /extract`. */
+export interface ExtractResult {
+    markdown: string;
+    metadata: ExtractionMeta;
+    requestId: string;
+}
+export declare function extractResultFromResponse(body: Record<string, unknown>): ExtractResult;
+/**
+ * One entry in a bulk job's `results` list.
+ *
+ * On success, `markdown` and `metadata` are populated and `error` is null.
+ * On a per-URL failure, `markdown`/`metadata` are null and `error` carries
+ * an API error code (e.g. `target_timeout`).
+ */
+export interface BulkItem {
+    url: string;
+    markdown: string | null;
+    metadata: ExtractionMeta | null;
+    error: string | null;
+    /** True when the item completed successfully (no error + has markdown). */
+    readonly ok: boolean;
+}
+export declare function bulkItemFromDict(data: Record<string, unknown>): BulkItem;
+/** "queued" | "processing" | "done" */
+export type JobStatus = "queued" | "processing" | "done";
+/**
+ * Status of a bulk extraction job.
+ *
+ * Returned from both `POST /bulk` and `GET /bulk/{jobId}`. Also one of the
+ * two possible return types from the polymorphic `WellMarked.getJob` and
+ * `WellMarked.waitForJob` — use the `kind` discriminator (or a type guard)
+ * to distinguish from `CrawlJob` if you need to read crawl-specific fields.
+ */
+export interface BulkJob {
+    readonly kind: "bulk";
+    jobId: string;
+    status: JobStatus;
+    total: number;
+    completed: number;
+    results: BulkItem[];
+    createdAt: Date | null;
+    finishedAt: Date | null;
+    /** True when `status === "done"`. */
+    readonly done: boolean;
+}
+export declare function bulkJobFromResponse(body: Record<string, unknown>): BulkJob;
+/**
+ * One page in a crawl job's `results` list.
+ *
+ * Shape mirrors `BulkItem` with an added `depth` field showing how far
+ * from the root URL this page sits in the BFS.
+ */
+export interface CrawlItem {
+    url: string;
+    depth: number;
+    markdown: string | null;
+    metadata: ExtractionMeta | null;
+    error: string | null;
+    /** True when the page completed successfully (no error + has markdown). */
+    readonly ok: boolean;
+}
+export declare function crawlItemFromDict(data: Record<string, unknown>): CrawlItem;
+export type TruncatedReason = "page_cap_reached" | "quota_exhausted";
+/**
+ * Status of a crawl job. Returned from `POST /crawl` and `GET /crawl/{jobId}`.
+ *
+ * Two crawl-only fields:
+ *   - `truncated`        — true when the crawl stopped before exhausting
+ *                          the frontier (depth/page cap or quota).
+ *   - `truncatedReason`  — `"page_cap_reached"` | `"quota_exhausted"` |
+ *                          `null`.
+ */
+export interface CrawlJob {
+    readonly kind: "crawl";
+    jobId: string;
+    status: JobStatus;
+    total: number;
+    completed: number;
+    results: CrawlItem[];
+    truncated: boolean;
+    truncatedReason: TruncatedReason | null;
+    createdAt: Date | null;
+    finishedAt: Date | null;
+    /** True when `status === "done"`. */
+    readonly done: boolean;
+}
+export declare function crawlJobFromResponse(body: Record<string, unknown>): CrawlJob;
+/**
+ * Result of `GET /usage` — current-period quota state.
+ *
+ * This is the source of truth for rate-limit / quota information. The SDK
+ * does not surface `X-RateLimit-*` headers on extract/bulk responses;
+ * call `WellMarked.getUsage()` instead.
+ */
+export interface Usage {
+    plan: string;
+    period: string;
+    used: number;
+    limit: number;
+    remaining: number;
+}
+export declare function usageFromResponse(body: Record<string, unknown>): Usage;
+/**
+ * Result of `POST /keys/rotate`.
+ *
+ * `apiKey` is the new raw key — store it before discarding this object,
+ * there is no recovery flow. The previous key is invalidated the moment
+ * the rotation call returns 200.
+ */
+export interface RotatedKey {
+    apiKey: string;
+    rotatedAt: Date | null;
+}
+export declare function rotatedKeyFromResponse(body: Record<string, unknown>): RotatedKey;
+export declare function isBulkJob(job: BulkJob | CrawlJob): job is BulkJob;
+export declare function isCrawlJob(job: BulkJob | CrawlJob): job is CrawlJob;

package/dist/esm/models.js

@@ -0,0 +1,154 @@
+/**
+ * Typed response objects returned by the WellMarked SDK.
+ *
+ * These mirror the JSON shapes documented at https://api.wellmarked.io/docs.
+ *
+ * Response objects carry only the body fields documented in the API
+ * reference — they do not surface HTTP headers. Quota state lives on the
+ * account, so use `WellMarked.getUsage()` to read it.
+ */
+function parseDate(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (value instanceof Date)
+        return value;
+    if (typeof value !== "string")
+        return null;
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+export function extractionMetaFromDict(data) {
+    return {
+        url: typeof data.url === "string" ? data.url : "",
+        title: typeof data.title === "string" ? data.title : null,
+        author: typeof data.author === "string" ? data.author : null,
+        date: typeof data.date === "string" ? data.date : null,
+        retrievedAt: parseDate(data.retrieved_at),
+    };
+}
+export function extractResultFromResponse(body) {
+    const rawMeta = body.metadata && typeof body.metadata === "object"
+        ? body.metadata
+        : {};
+    return {
+        markdown: typeof body.markdown === "string" ? body.markdown : "",
+        metadata: extractionMetaFromDict(rawMeta),
+        requestId: typeof body.request_id === "string" ? body.request_id : "",
+    };
+}
+export function bulkItemFromDict(data) {
+    const rawMeta = data.metadata;
+    const url = typeof data.url === "string" ? data.url : "";
+    const markdown = typeof data.markdown === "string" ? data.markdown : null;
+    const error = typeof data.error === "string" ? data.error : null;
+    const metadata = rawMeta && typeof rawMeta === "object"
+        ? extractionMetaFromDict(rawMeta)
+        : null;
+    return {
+        url,
+        markdown,
+        metadata,
+        error,
+        get ok() {
+            return error === null && markdown !== null;
+        },
+    };
+}
+export function bulkJobFromResponse(body) {
+    const rawResults = Array.isArray(body.results) ? body.results : [];
+    const status = typeof body.status === "string" ? body.status : "queued";
+    const jobId = typeof body.job_id === "string" ? body.job_id : "";
+    const total = typeof body.total === "number" ? body.total : 0;
+    const completed = typeof body.completed === "number" ? body.completed : 0;
+    const createdAt = parseDate(body.created_at);
+    const finishedAt = parseDate(body.finished_at);
+    const results = rawResults
+        .filter((r) => r !== null && typeof r === "object")
+        .map(bulkItemFromDict);
+    return {
+        kind: "bulk",
+        jobId,
+        status,
+        total,
+        completed,
+        results,
+        createdAt,
+        finishedAt,
+        get done() {
+            return status === "done";
+        },
+    };
+}
+export function crawlItemFromDict(data) {
+    const rawMeta = data.metadata;
+    const url = typeof data.url === "string" ? data.url : "";
+    const depth = typeof data.depth === "number" ? data.depth : 0;
+    const markdown = typeof data.markdown === "string" ? data.markdown : null;
+    const error = typeof data.error === "string" ? data.error : null;
+    const metadata = rawMeta && typeof rawMeta === "object"
+        ? extractionMetaFromDict(rawMeta)
+        : null;
+    return {
+        url,
+        depth,
+        markdown,
+        metadata,
+        error,
+        get ok() {
+            return error === null && markdown !== null;
+        },
+    };
+}
+export function crawlJobFromResponse(body) {
+    const rawResults = Array.isArray(body.results) ? body.results : [];
+    const status = typeof body.status === "string" ? body.status : "queued";
+    const jobId = typeof body.job_id === "string" ? body.job_id : "";
+    const total = typeof body.total === "number" ? body.total : 0;
+    const completed = typeof body.completed === "number" ? body.completed : 0;
+    const createdAt = parseDate(body.created_at);
+    const finishedAt = parseDate(body.finished_at);
+    const truncated = body.truncated === true;
+    const truncatedReason = typeof body.truncated_reason === "string"
+        ? body.truncated_reason
+        : null;
+    const results = rawResults
+        .filter((r) => r !== null && typeof r === "object")
+        .map(crawlItemFromDict);
+    return {
+        kind: "crawl",
+        jobId,
+        status,
+        total,
+        completed,
+        results,
+        truncated,
+        truncatedReason,
+        createdAt,
+        finishedAt,
+        get done() {
+            return status === "done";
+        },
+    };
+}
+export function usageFromResponse(body) {
+    return {
+        plan: typeof body.plan === "string" ? body.plan : "",
+        period: typeof body.period === "string" ? body.period : "",
+        used: typeof body.used === "number" ? body.used : 0,
+        limit: typeof body.limit === "number" ? body.limit : 0,
+        remaining: typeof body.remaining === "number" ? body.remaining : 0,
+    };
+}
+export function rotatedKeyFromResponse(body) {
+    return {
+        apiKey: typeof body.api_key === "string" ? body.api_key : "",
+        rotatedAt: parseDate(body.rotated_at),
+    };
+}
+// ── Type guards ──────────────────────────────────────────────────────────────
+export function isBulkJob(job) {
+    return job.kind === "bulk";
+}
+export function isCrawlJob(job) {
+    return job.kind === "crawl";
+}

package/dist/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "1.0.0";

package/dist/esm/version.js

@@ -0,0 +1 @@
+export const VERSION = "1.0.0";