wellmarked 1.1.0

package/dist/types/client.d.ts

@@ -0,0 +1,173 @@
+/**
+ * WellMarked client.
+ *
+ * The client is a thin, typed wrapper around the HTTP API. All endpoint
+ * methods are async — there is no separate sync/async split as in the
+ * Python SDK because JavaScript I/O is async by default.
+ *
+ *     import { WellMarked } from "wellmarked";
+ *
+ *     const wm = new WellMarked({ apiKey: "wm_..." });
+ *     const result = await wm.extract("https://example.com/article");
+ *     console.log(result.markdown);
+ *
+ * The API key can also be passed via the `WELLMARKED_API_KEY` environment
+ * variable (Node.js), in which case `new WellMarked()` is enough.
+ */
+import { APIStatusError } from "./errors.js";
+import { type BulkJob, type CrawlJob, type ExtractResult, type RotatedKey, type Usage } from "./models.js";
+export interface WellMarkedOptions {
+    /**
+     * Your WellMarked API key (`wm_...`). Falls back to the
+     * `WELLMARKED_API_KEY` environment variable (Node.js only).
+     */
+    apiKey?: string;
+    /** API base URL. Override for testing. */
+    baseUrl?: string;
+    /** Per-request timeout, milliseconds. Defaults to 30000 (30s). */
+    timeoutMs?: number;
+    /**
+     * Bring your own `fetch`. Defaults to the global `fetch`. Useful for
+     * polyfills, custom agents/proxies, or test mocking.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers sent on every request — useful for adding an internal
+     * correlation id, a custom user agent suffix, etc.
+     *
+     * Authorization / Content-Type / Accept are reserved and silently
+     * ignored if passed (the SDK manages those itself).
+     */
+    headers?: Record<string, string>;
+}
+export interface ExtractOptions {
+    /**
+     * Use Playwright to render JS-heavy pages. Requires a Pro/Enterprise
+     * plan AND `ENABLE_JS_RENDERING=true` on the API instance.
+     */
+    renderJs?: boolean;
+}
+export interface BulkOptions {
+    renderJs?: boolean;
+}
+export interface CrawlOptions {
+    /** Max BFS depth from the root. Defaults to 1. Must be >= 0. */
+    depth?: number;
+    renderJs?: boolean;
+}
+export interface WaitForJobOptions {
+    /** Milliseconds to sleep between polls. Defaults to 2000. */
+    pollIntervalMs?: number;
+    /** Total ms to wait before timing out. `null` waits forever. Defaults to 300000 (5 min). */
+    timeoutMs?: number | null;
+}
+export declare class WellMarked {
+    private apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly extraHeaders;
+    constructor(options?: WellMarkedOptions);
+    /**
+     * Extract clean Markdown from a single URL.
+     *
+     * Throws:
+     *   - `RateLimitError`            — monthly plan limit reached.
+     *   - `UnprocessableEntityError`  — `no_content`, `target_timeout`, or
+     *                                   `js_rendering_disabled`.
+     *   - `AuthenticationError`       — missing or invalid API key.
+     */
+    extract(url: string, options?: ExtractOptions): Promise<ExtractResult>;
+    /**
+     * Submit a batch of URLs for concurrent extraction.
+     *
+     * Returns immediately with `status="queued"`. Poll with `getJob` or
+     * block with `waitForJob` to collect results.
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `bulk_cap_exceeded` (50 on Pro).
+     *   - `RateLimitError`            — would exceed remaining monthly quota.
+     */
+    bulk(urls: Iterable<string>, options?: BulkOptions): Promise<BulkJob>;
+    /**
+     * Polymorphic job lookup — works for both bulk and crawl jobs.
+     *
+     * Calls `GET /bulk/{jobId}` first, then inspects the response's `kind`
+     * discriminator field. If the job is actually a crawl, a second request
+     * to `GET /crawl/{jobId}` fetches the full crawl shape (with per-item
+     * depth and the truncated flags). Returns `BulkJob` or `CrawlJob`
+     * accordingly.
+     *
+     * Use `isCrawlJob(job)` (or check `job.kind === "crawl"`) to branch on
+     * crawl-specific behavior. The shared interface (`status`, `completed`,
+     * `total`, `results`, `done`) works on either type.
+     *
+     * Jobs are retained for 6 hours after completion.
+     */
+    getJob(jobId: string): Promise<BulkJob | CrawlJob>;
+    /**
+     * Block until a job reaches `status="done"` (or timeout). Works for both
+     * bulk and crawl jobs.
+     *
+     * The first call uses the polymorphic `getJob` to discover the job's
+     * kind. Subsequent polls go directly to the typed endpoint, so a crawl
+     * job only pays the dispatch round-trip once.
+     *
+     * Throws:
+     *   - `Error` with message "did not finish within ..." — the job didn't
+     *     finish before `timeoutMs` elapsed.
+     */
+    waitForJob(jobId: string, options?: WaitForJobOptions): Promise<BulkJob | CrawlJob>;
+    /**
+     * Crawl a site starting from `url`, BFS to `depth`.
+     *
+     * Returns immediately with `status="queued"`. Use `getJob` to poll, or
+     * `waitForJob` to block until done — both handle crawl and bulk jobIds
+     * transparently.
+     *
+     * Plan caps:
+     *   - Free        → `PermissionDeniedError` (`plan_not_supported`)
+     *   - Pro         → max depth 5, up to 1,000 pages per crawl
+     *   - Enterprise  → unlimited depth and pages
+     *
+     * Throws:
+     *   - `PermissionDeniedError`     — `plan_not_supported` (Free tier).
+     *   - `UnprocessableEntityError`  — `crawl_depth_exceeded`.
+     */
+    crawl(url: string, options?: CrawlOptions): Promise<CrawlJob>;
+    /**
+     * Add or replace a per-request header for the rest of this client's life.
+     *
+     * Authorization / Content-Type / Accept are reserved — calls that try
+     * to set those are silently ignored. To rotate the bearer token, use
+     * `rotateKey()`.
+     */
+    setHeader(name: string, value: string): void;
+    /** Remove a header previously added via `headers:` or `setHeader()`. */
+    removeHeader(name: string): void;
+    /**
+     * Return your usage for the current billing period.
+     *
+     * Does not count toward your monthly quota.
+     */
+    getUsage(): Promise<Usage>;
+    /**
+     * Mint a new API key. The current key is invalidated immediately.
+     *
+     * The new raw key is in the returned `apiKey` field — store it before
+     * discarding the result. There is no recovery flow.
+     *
+     * The client auto-swaps to the new key for subsequent requests.
+     *
+     * Does not count toward your monthly quota.
+     */
+    rotateKey(): Promise<RotatedKey>;
+    /**
+     * Internal: read the current API key. Exposed for tests.
+     * Not part of the public, semver-stable surface.
+     */
+    _getApiKey(): string;
+    private request;
+}
+export { APIStatusError };

package/dist/types/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/types/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/types/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/types/version.d.ts

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "wellmarked",
+  "version": "1.1.0",
+  "description": "Official JavaScript/TypeScript SDK for the WellMarked API — convert any URL to clean Markdown.",
+  "keywords": [
+    "wellmarked",
+    "markdown",
+    "scraping",
+    "extraction",
+    "html-to-markdown",
+    "rag",
+    "llm",
+    "pipeline"
+  ],
+  "homepage": "https://wellmarked.io",
+  "bugs": {
+    "url": "https://github.com/WellMarkedAPI/WellMarked/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WellMarkedAPI/WellMarked.git",
+    "directory": "js-sdk"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "WellMarked",
+    "email": "support@wellmarked.io",
+    "url": "https://wellmarked.io"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "npm run build:clean && npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:clean": "rimraf dist",
+    "build:esm": "tsc -p tsconfig.build.json --module esnext --moduleResolution bundler --outDir dist/esm",
+    "build:cjs": "tsc -p tsconfig.build.json --module commonjs --moduleResolution node --outDir dist/cjs && node scripts/rename-cjs.mjs",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --outDir dist/types",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}