sendscore 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SendScore
+
+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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# SendScore for TypeScript and JavaScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed wrapper around the [SendScore](https://github.com/sendscore/sendscore) CLI, which checks a newsletter email before it goes out. Every language package runs the same binary, so they all return the same verdict.
+
+Not published yet.
+
+```sh
+npm install sendscore
+```
+
+It also gives you the `sendscore` command, which takes the same arguments and exit codes as the CLI.
+
+```sh
+npx sendscore check issue.eml
+npm install -g sendscore
+```
+
+```ts
+import { check, diff } from "sendscore";
+
+const verdict = await check("issue.eml");
+if (!verdict.ready_to_send) {
+  for (const fix of verdict.top_fixes) console.log(fix.who, fix.fix);
+}
+
+await check(rawBytes, { offline: true });
+await diff("before.eml", "after.eml");
+```
+
+A message that fails its checks is still a report, so `check` returns it. `SendScoreError` is thrown only when no report could be made, and its `exitCode` is the CLI's. Receipt at SendScore does not prove inbox placement at Gmail or any other provider.
+
+Pass `timeout` in milliseconds to `check` or `diff` to kill the CLI when it runs out. A killed CLI raises `SendScoreError` with `exitCode` set to `KILLED`, which is -1.
+
+## The binary
+
+The binary installs with the package. `npm install sendscore` also installs one `@sendscore/cli-<os>-<arch>` package for your machine, through `optionalDependencies`, on macOS, Linux, and Windows, for x64 and arm64. Nothing runs at install time, and nothing is downloaded when you use it.
+
+The package uses `SENDSCORE_BIN`, then that bundled binary, then the CLI on `PATH` if its version matches, then your user cache. If you install with optional dependencies turned off, the first call downloads the pinned release from GitHub, and checks it against the SHA-256 values in the package before it runs anything, including a cached binary.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// The sendscore command: finds the CLI the same way the library does, then
+// runs it with this process's arguments, streams, and exit code.
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { binary } from "./index.js";
+// EX_SOFTWARE, as the CLI uses for an internal error.
+const INTERNAL = 70;
+// The PATH search may find this launcher and run it to read its version. The
+// mark makes that run fail at once, so the search moves on instead of looping.
+const MARK = "SENDSCORE_LAUNCHED";
+function fail(message) {
+    process.stderr.write(`sendscore: ${message}\n`);
+    process.exit(INTERNAL);
+}
+if (process.env[MARK])
+    fail("found itself instead of the CLI");
+process.env[MARK] = "1";
+let path;
+try {
+    path = await binary();
+}
+catch (e) {
+    fail(e.message);
+}
+const child = spawn(path, process.argv.slice(2), { stdio: "inherit", shell: false, windowsHide: false });
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => child.kill(signal));
+}
+child.on("error", (e) => fail(`could not run ${path}: ${e.message}`));
+child.on("exit", (code, signal) => {
+    // A shell reports a process killed by a signal as 128 plus its number.
+    process.exit(code ?? 128 + (signal ? constants.signals[signal] : 0));
+});

package/dist/download.d.ts

@@ -0,0 +1,28 @@
+export declare const RELEASES = "https://github.com/sendscore/sendscore/releases/download";
+export interface Platform {
+    os: string;
+    arch: string;
+}
+/** The SHA-256 of a release archive and of the binary inside it. */
+export interface Pin {
+    archive: string;
+    binary: string;
+}
+export declare function currentPlatform(): Platform;
+export declare function cacheRoot(): string;
+/** The pin for a platform. With none, nothing may be downloaded or trusted from the cache. */
+export declare function pinFor(p: Platform, pins?: Record<string, Pin>): Pin;
+/** Whether a file exists and is exactly the pinned binary. */
+export declare function matchesPin(path: string, pin: Pin): Promise<boolean>;
+/** The name of the release archive for a version and platform. */
+export declare function archiveName(version: string, p: Platform): string;
+/** Reads one file, by its exact name, from a tar archive. Nothing else is touched. */
+export declare function fromTar(tar: Buffer, name: string): Buffer | undefined;
+/** Reads one file, by its exact name, from a zip archive. Nothing else is touched. */
+export declare function fromZip(zip: Buffer, name: string): Buffer | undefined;
+/**
+ * Downloads a release into dir, and returns the binary's path. The archive
+ * must match its pin before anything is extracted, and the binary must match
+ * its pin before it reaches the disk.
+ */
+export declare function download(version: string, base: string, dir: string, pin: Pin, p?: Platform): Promise<string>;

package/dist/download.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+import { SendScoreError } from "./error.js";
+import { HASHES } from "./hashes.js";
+export const RELEASES = "https://github.com/sendscore/sendscore/releases/download";
+const MAX_DOWNLOAD = 100 * 1024 * 1024;
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+const OS = { linux: "linux", darwin: "darwin", win32: "windows" };
+const ARCH = { x64: "amd64", arm64: "arm64" };
+export function currentPlatform() {
+    const os = OS[process.platform];
+    const arch = ARCH[process.arch];
+    if (!os || !arch) {
+        throw new SendScoreError(`no SendScore build for ${process.platform} on ${process.arch}`, 0);
+    }
+    return { os, arch };
+}
+export function cacheRoot() {
+    if (process.platform === "darwin")
+        return join(homedir(), "Library", "Caches");
+    if (process.platform === "win32")
+        return process.env["LOCALAPPDATA"] || join(homedir(), "AppData", "Local");
+    const xdg = process.env["XDG_CACHE_HOME"];
+    return xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".cache");
+}
+/** The pin for a platform. With none, nothing may be downloaded or trusted from the cache. */
+export function pinFor(p, pins = HASHES) {
+    const pin = pins[`${p.os}_${p.arch}`];
+    if (!pin) {
+        throw new SendScoreError(`this package has no pinned hash for ${p.os}_${p.arch}, so it will not download a CLI. Install the matching sendscore on PATH, or set SENDSCORE_BIN.`, 0);
+    }
+    return pin;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Whether a file exists and is exactly the pinned binary. */
+export async function matchesPin(path, pin) {
+    try {
+        return sha256(await readFile(path)) === pin.binary;
+    }
+    catch {
+        return false;
+    }
+}
+/** The name of the release archive for a version and platform. */
+export function archiveName(version, p) {
+    return `sendscore_${version}_${p.os}_${p.arch}.${p.os === "windows" ? "zip" : "tar.gz"}`;
+}
+async function fetchBytes(url) {
+    try {
+        const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+        if (!res.ok || !res.body)
+            throw new SendScoreError(`download of ${url} answered ${res.status}`, 0);
+        const parts = [];
+        let size = 0;
+        for await (const part of res.body) {
+            size += part.length;
+            if (size > MAX_DOWNLOAD)
+                throw new SendScoreError(`download of ${url} is too large`, 0);
+            parts.push(part);
+        }
+        return Buffer.concat(parts);
+    }
+    catch (e) {
+        if (e instanceof SendScoreError)
+            throw e;
+        throw new SendScoreError(`download of ${url} failed: ${e.message}`, 0);
+    }
+}
+/** Reads one file, by its exact name, from a tar archive. Nothing else is touched. */
+export function fromTar(tar, name) {
+    for (let at = 0; at + 512 <= tar.length;) {
+        const header = tar.subarray(at, at + 512);
+        if (header.every((b) => b === 0))
+            return undefined;
+        const end = header.indexOf(0);
+        const entry = header.subarray(0, end < 0 || end > 100 ? 100 : end).toString();
+        const size = parseInt(header.subarray(124, 136).toString().replace(/\0.*$/, "").trim() || "0", 8);
+        const type = header[156];
+        at += 512;
+        if (entry === name && (type === 0 || type === 48))
+            return tar.subarray(at, at + size);
+        at += Math.ceil(size / 512) * 512;
+    }
+    return undefined;
+}
+/** Reads one file, by its exact name, from a zip archive. Nothing else is touched. */
+export function fromZip(zip, name) {
+    let end = zip.length - 22;
+    while (end >= 0 && zip.readUInt32LE(end) !== 0x06054b50)
+        end--;
+    if (end < 0)
+        return undefined;
+    const count = zip.readUInt16LE(end + 10);
+    let at = zip.readUInt32LE(end + 16);
+    for (let i = 0; i < count; i++) {
+        const method = zip.readUInt16LE(at + 10);
+        const packed = zip.readUInt32LE(at + 20);
+        const nameLen = zip.readUInt16LE(at + 28);
+        const extraLen = zip.readUInt16LE(at + 30);
+        const commentLen = zip.readUInt16LE(at + 32);
+        const local = zip.readUInt32LE(at + 42);
+        if (zip.subarray(at + 46, at + 46 + nameLen).toString() === name) {
+            const start = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+            const data = zip.subarray(start, start + packed);
+            return method === 0 ? data : inflateRawSync(data);
+        }
+        at += 46 + nameLen + extraLen + commentLen;
+    }
+    return undefined;
+}
+/**
+ * Downloads a release into dir, and returns the binary's path. The archive
+ * must match its pin before anything is extracted, and the binary must match
+ * its pin before it reaches the disk.
+ */
+export async function download(version, base, dir, pin, p = currentPlatform()) {
+    const binName = p.os === "windows" ? "sendscore.exe" : "sendscore";
+    const target = join(dir, binName);
+    const name = archiveName(version, p);
+    const archive = await fetchBytes(`${base}/${name}`);
+    if (sha256(archive) !== pin.archive) {
+        throw new SendScoreError(`${name} does not match its pinned hash`, 0);
+    }
+    const binary = p.os === "windows" ? fromZip(archive, binName) : fromTar(gunzipSync(archive), binName);
+    if (!binary)
+        throw new SendScoreError(`${name} has no ${binName}`, 0);
+    if (sha256(binary) !== pin.binary) {
+        throw new SendScoreError(`the binary in ${name} does not match its pinned hash`, 0);
+    }
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const temp = await mkdtemp(join(dir, ".download-"));
+        try {
+            const path = join(temp, binName);
+            await writeFile(path, binary, { mode: 0o755 });
+            await chmod(path, 0o755);
+            await rename(path, target);
+        }
+        finally {
+            await rm(temp, { recursive: true, force: true });
+        }
+    }
+    catch (e) {
+        throw new SendScoreError(`could not write to ${dir}: ${e.message}`, 0);
+    }
+    return target;
+}

package/dist/error.d.ts

@@ -0,0 +1,8 @@
+/** The exitCode of a CLI that was killed, or stopped by a timeout. */
+export declare const KILLED = -1;
+/** The CLI could not produce a report, or could not be found or installed. */
+export declare class SendScoreError extends Error {
+    /** The CLI's exit code: 64 and above, 0 when the CLI never ran, or KILLED. */
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number);
+}

package/dist/error.js

@@ -0,0 +1,12 @@
+/** The exitCode of a CLI that was killed, or stopped by a timeout. */
+export const KILLED = -1;
+/** The CLI could not produce a report, or could not be found or installed. */
+export class SendScoreError extends Error {
+    /** The CLI's exit code: 64 and above, 0 when the CLI never ran, or KILLED. */
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.name = "SendScoreError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/hashes.d.ts

@@ -0,0 +1,4 @@
+export declare const HASHES: Record<string, {
+    archive: string;
+    binary: string;
+}>;

package/dist/hashes.js

@@ -0,0 +1,9 @@
+// Generated by scripts/pinhashes. Do not edit.
+export const HASHES = {
+    darwin_amd64: { archive: "d79c0d7d6f41322caf56f2ab90b6d61f25b97109f3449d84964751e9e9a685bb", binary: "a508ff1a9bc8e63d5f79f663d5596cdd1c4cb6803d051d3c91a5a9481870dae1" },
+    darwin_arm64: { archive: "899eeac2be04f1d0619829cd0eb9fc171e358a0deb409e8dee74e3c95543bfac", binary: "4e3ea55cc7bfa9d00d4b4742720ca475e8354052008a8133b0eeea9b17e6c109" },
+    linux_amd64: { archive: "c9bee6d95e057da006c27b015697db02f8d40f5f933c2c0f8956d33adc304bc8", binary: "87a3c521bbf05516267757eb979f14bc66a2289cc5d5c86a8955186e984ff7da" },
+    linux_arm64: { archive: "69c75e7bd97f5f4e1e5f67f9eaa9efa808ef1264550385887c7222ff6370e6a1", binary: "c0d25f8d93b8b202fa1b78e4275da41fe8e637dc256b03b19eed3af38e0b2c99" },
+    windows_amd64: { archive: "68f136dfd60a370512b97080781005c7cbffc00ce318bc77f5f347ae1625265f", binary: "d2da36431144d87971a33ee9e59590f281fb84b8acf3b8814e989073e90f4866" },
+    windows_arm64: { archive: "f3f2d796add9f0690e447239931b6bd0e99ff25e6ea9553f205e88821e9b4761", binary: "b78b9923bb5a6f7f0040969162e67417292d6e3558451a5faa7de18510398862" },
+};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { pinFor } from "./download.js";
+import type { CheckOptions, DiffOptions, DiffResult, Verdict } from "./types.js";
+export * from "./types.js";
+export { KILLED, SendScoreError } from "./error.js";
+/** The CLI release this package downloads when none is installed. */
+export declare const ENGINE_VERSION = "0.3.0";
+/**
+ * Finds the CLI: SENDSCORE_BIN, then the binary installed with this package,
+ * then the pinned version on PATH, then the cache, then a download. A cached
+ * binary is checked against its pinned hash every time, so a file planted in
+ * the cache is replaced and never run.
+ */
+export declare function binary(): Promise<string>;
+/**
+ * The binary from this platform's package, or null. npm installs only the
+ * package that matches this machine. It came with this code, so it is trusted
+ * as this code is, and needs no version check or hash.
+ */
+export declare function bundled(): Promise<string | null>;
+/** The pinned version on PATH, or null. Exported for tests. */
+export declare function onPath(): Promise<string | null>;
+/** The cached binary, or a download, as the pins allow. Exported for tests. */
+export declare function installed(pins?: Parameters<typeof pinFor>[1]): Promise<string>;
+/**
+ * Checks one message, given as a path or as its bytes. A message that fails
+ * checks is still a report: this throws only when no report could be made.
+ */
+export declare function check(message: string | Uint8Array, options?: CheckOptions): Promise<Verdict>;
+/** Compares two saved messages, given as paths. */
+export declare function diff(before: string, after: string, options?: DiffOptions): Promise<DiffResult>;

package/dist/index.js

@@ -0,0 +1,176 @@
+import { spawn } from "node:child_process";
+import { access, constants, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { RELEASES, cacheRoot, currentPlatform, download, matchesPin, pinFor } from "./download.js";
+import { KILLED, SendScoreError } from "./error.js";
+export * from "./types.js";
+export { KILLED, SendScoreError } from "./error.js";
+/** The CLI release this package downloads when none is installed. */
+export const ENGINE_VERSION = "0.3.0";
+const exe = process.platform === "win32" ? "sendscore.exe" : "sendscore";
+const VERSION_TIMEOUT_MS = 10_000;
+async function executable(path) {
+    try {
+        if (!(await stat(path)).isFile())
+            return false;
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a CLI reports the version this package was tested against. */
+async function rightVersion(path) {
+    try {
+        const r = await run(path, ["--version"], undefined, VERSION_TIMEOUT_MS);
+        const version = r.stdout.trim().split(/\s+/).pop() ?? "";
+        return r.code === 0 && version.replace(/^v/, "") === ENGINE_VERSION;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Finds the CLI: SENDSCORE_BIN, then the binary installed with this package,
+ * then the pinned version on PATH, then the cache, then a download. A cached
+ * binary is checked against its pinned hash every time, so a file planted in
+ * the cache is replaced and never run.
+ */
+export async function binary() {
+    const fromEnv = process.env["SENDSCORE_BIN"];
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return (await bundled()) ?? (await onPath()) ?? (await installed());
+    }
+    catch (e) {
+        if (e instanceof SendScoreError)
+            throw e;
+        throw new SendScoreError(`could not find or install the CLI: ${e.message}`, 0);
+    }
+}
+/**
+ * The binary from this platform's package, or null. npm installs only the
+ * package that matches this machine. It came with this code, so it is trusted
+ * as this code is, and needs no version check or hash.
+ */
+export async function bundled() {
+    try {
+        const name = `@sendscore/cli-${process.platform}-${process.arch}`;
+        const path = join(dirname(createRequire(import.meta.url).resolve(`${name}/package.json`)), "bin", exe);
+        return (await executable(path)) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The pinned version on PATH, or null. Exported for tests. */
+export async function onPath() {
+    for (const dir of (process.env["PATH"] ?? "").split(delimiter)) {
+        if (!isAbsolute(dir))
+            continue;
+        const path = join(dir, exe);
+        if ((await executable(path)) && (await rightVersion(path)))
+            return path;
+    }
+    return null;
+}
+/** The cached binary, or a download, as the pins allow. Exported for tests. */
+export async function installed(pins) {
+    const platform = currentPlatform();
+    const pin = pinFor(platform, pins);
+    const dir = join(cacheRoot(), "sendscore", ENGINE_VERSION);
+    if (await matchesPin(join(dir, exe), pin))
+        return join(dir, exe);
+    return await download(ENGINE_VERSION, `${RELEASES}/v${ENGINE_VERSION}`, dir, pin, platform);
+}
+function run(bin, args, stdin, timeout) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        let timedOut = false;
+        const timer = timeout === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, timeout);
+        child.stdout.on("data", (b) => out.push(b));
+        child.stderr.on("data", (b) => err.push(b));
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new SendScoreError(`could not run ${bin}: ${e.message}`, 0));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                reject(new SendScoreError(`sendscore did not finish within ${timeout} ms`, KILLED));
+                return;
+            }
+            resolve({
+                code: code === null || code < 0 || code >= 128 ? KILLED : code,
+                stdout: Buffer.concat(out).toString(),
+                stderr: Buffer.concat(err).toString(),
+            });
+        });
+        if (stdin) {
+            child.stdin.on("error", () => { });
+            child.stdin.end(stdin);
+        }
+    });
+}
+function parse(r, verdictCodes) {
+    if (!verdictCodes.includes(r.code)) {
+        throw new SendScoreError(r.stderr.trim() || `sendscore exited ${r.code}`, r.code);
+    }
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        throw new SendScoreError("sendscore printed something that is not JSON", r.code);
+    }
+}
+/** A lone `-` would mean standard input to the CLI, so a file of that name gets a path. */
+function pathArg(path) {
+    return path === "-" ? "./-" : path;
+}
+/**
+ * Checks one message, given as a path or as its bytes. A message that fails
+ * checks is still a report: this throws only when no report could be made.
+ */
+export async function check(message, options = {}) {
+    const args = ["check", "--json"];
+    if (options.offline)
+        args.push("--offline");
+    if (options.links)
+        args.push("--links");
+    if (options.ip !== undefined)
+        args.push("--ip", options.ip);
+    if (options.mailFrom !== undefined)
+        args.push("--mail-from", options.mailFrom);
+    if (options.helo !== undefined)
+        args.push("--helo", options.helo);
+    if (options.tls !== undefined)
+        args.push("--tls", options.tls ? "yes" : "no");
+    if (options.previous !== undefined)
+        args.push("--previous", pathArg(options.previous));
+    const stdin = typeof message === "string" ? undefined : message;
+    args.push("--", typeof message === "string" ? pathArg(message) : "-");
+    const verdict = parse(await run(await binary(), args, stdin, options.timeout), [0, 1, 2]);
+    if (typeof verdict?.schema !== "string" || !verdict.schema.startsWith("sendscore.verdict/")) {
+        throw new SendScoreError("sendscore printed something that is not a verdict", 0);
+    }
+    return verdict;
+}
+/** Compares two saved messages, given as paths. */
+export async function diff(before, after, options = {}) {
+    const args = ["diff", "--json", "--", pathArg(before), pathArg(after)];
+    const result = parse(await run(await binary(), args, undefined, options.timeout), [0, 1]);
+    if (result === null || typeof result !== "object" || !("changes" in result)) {
+        throw new SendScoreError("sendscore printed something that is not a comparison", 0);
+    }
+    return { ...result, changes: result.changes ?? [] };
+}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/** The `sendscore.verdict/v1` report. New fields may appear in this version. */
+export type Status = "pass" | "warn" | "fail" | "info" | "skipped";
+export type Category = "auth" | "unsub" | "struct" | "content" | "delivery" | "changes";
+export type Who = "you" | "provider";
+export interface Message {
+    received_at: string;
+    from: string;
+    subject: string;
+    message_id: string;
+    size_bytes: number;
+}
+export interface Fix {
+    who: Who;
+    text: string;
+}
+export interface Check {
+    id: string;
+    category: Category;
+    status: Status;
+    title: string;
+    detail?: string;
+    evidence?: Record<string, unknown>;
+    fix?: Fix;
+    docs?: string;
+    /** Why the check was skipped. */
+    reason?: string;
+}
+export interface TopFix {
+    check: string;
+    who: Who;
+    fix: string;
+}
+export interface Change {
+    field: string;
+    before: unknown;
+    after: unknown;
+    /** The check this change made worse, if any. */
+    worsened?: string;
+}
+export interface Fingerprint {
+    dkim_domains: string[];
+    dkim_selectors: string[];
+    return_path_domain: string;
+    remote_ip?: string;
+    ptr?: string;
+    list_unsubscribe: boolean;
+    one_click: boolean;
+    link_hosts: string[];
+    html_bytes: number;
+    links: number;
+    images: number;
+    auth: Record<string, Status> | null;
+}
+export interface Verdict {
+    schema: string;
+    id?: string;
+    message: Message;
+    publication?: string;
+    verdict: Status;
+    ready_to_send: boolean;
+    summary: string;
+    top_fixes: TopFix[];
+    checks: Check[];
+    changes: Change[];
+    fingerprint?: Fingerprint;
+    explanation: string | null;
+    note: string;
+}
+export interface DiffResult {
+    before: string;
+    after: string;
+    changes: Change[];
+}
+export interface CheckOptions {
+    /** Make no DNS lookups. Checks that need DNS are skipped. */
+    offline?: boolean;
+    /** Fetch every link and image, never unsubscribe or confirm links. */
+    links?: boolean;
+    /** IP address of the server that delivered the message. */
+    ip?: string;
+    /** Envelope sender. Defaults to the Return-Path. */
+    mailFrom?: string;
+    /** HELO name the delivering server gave. */
+    helo?: string;
+    /** Whether delivery used TLS. */
+    tls?: boolean;
+    /** Path of the publication's previous issue, to list what changed. */
+    previous?: string;
+    /** Kill the CLI and throw after this many milliseconds. No limit by default. */
+    timeout?: number;
+}
+/** What a comparison should do beyond reading the messages. */
+export interface DiffOptions {
+    /** Kill the CLI and throw after this many milliseconds. No limit by default. */
+    timeout?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** The `sendscore.verdict/v1` report. New fields may appear in this version. */
+export {};

package/package.json

@@ -1,6 +1,39 @@
 {
+  "bin": {
+    "sendscore": "dist/cli.js"
+  },
+  "description": "Check a newsletter email before it goes out. A typed wrapper around the SendScore CLI.",
+  "engines": {
+    "node": "\u003e=20"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
   "name": "sendscore",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "optionalDependencies": {
+    "@sendscore/cli-darwin-arm64": "0.3.0",
+    "@sendscore/cli-darwin-x64": "0.3.0",
+    "@sendscore/cli-linux-arm64": "0.3.0",
+    "@sendscore/cli-linux-x64": "0.3.0",
+    "@sendscore/cli-win32-arm64": "0.3.0",
+    "@sendscore/cli-win32-x64": "0.3.0"
+  },
+  "repository": {
+    "directory": "packages/sdk",
+    "type": "git",
+    "url": "git+https://github.com/sendscore/sendscore.git"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.3.0"
+}