linkedin-toolkit-mcp 2.0.2 → 2.1.0

package/dist/setup.d.ts

@@ -0,0 +1,248 @@
+/**
+ * `lit setup` — everything between "I found this repo" and "my agent can use
+ * it", minus the three clicks Chrome will not let anybody automate.
+ *
+ * The old path was: find the Releases page, download a zip, unzip it somewhere
+ * you will not delete, turn on Developer mode, Load unpacked, run a server,
+ * find the pairing token, paste it, then hand-write a JSON config block for
+ * whichever agent you use. Seven steps, six of which a computer can do.
+ *
+ * This module does the six. Everything here is a small function with its
+ * dependencies passed in — `fetch`, the filesystem, the clock, the
+ * environment — so the whole flow is testable without a network, a Chrome, or
+ * a home directory.
+ *
+ * What it deliberately does not do:
+ *   - claim Chrome opened a page it may have ignored (see `chromeLaunch`);
+ *   - write a client config file it cannot parse (a malformed file is refused,
+ *     never rewritten);
+ *   - install anything outside `~/.linkedin-toolkit` unless asked.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, copyFileSync } from 'node:fs';
+export declare const REPO = "OpenRecruiterTools/linkedin-toolkit";
+export declare const RELEASES_URL = "https://github.com/OpenRecruiterTools/linkedin-toolkit/releases";
+/** A setup step that failed for a reason the user can act on. */
+export declare class SetupError extends Error {
+    readonly howToFix?: string | undefined;
+    constructor(message: string, howToFix?: string | undefined);
+}
+/** The slice of `node:fs` this module uses, so tests can pass their own. */
+export type FsLike = {
+    existsSync: typeof existsSync;
+    mkdirSync: typeof mkdirSync;
+    readFileSync: typeof readFileSync;
+    readdirSync: typeof readdirSync;
+    renameSync: typeof renameSync;
+    rmSync: typeof rmSync;
+    writeFileSync: typeof writeFileSync;
+    copyFileSync: typeof copyFileSync;
+};
+export declare const realFs: FsLike;
+/**
+ * The release asset for one version.
+ *
+ * The release workflow names the zip from the tag, so `linkedin-toolkit-mcp`
+ * 2.1.0 and `linkedin-toolkit-extension-v2.1.0.zip` are the same release by
+ * construction. A version the user passed by hand may carry a leading `v`.
+ */
+export declare function extensionZipUrl(version: string): string;
+/** The API read that answers "what is the newest release, and what is in it?" */
+export declare function latestReleaseApiUrl(): string;
+export type Download = {
+    url: string;
+    version: string;
+    /** `version` when the exact release existed, `latest` when we fell back. */
+    source: 'version' | 'latest';
+};
+/**
+ * Resolve the newest release's extension asset.
+ *
+ * `releases/latest/download/<name>` cannot be used directly because the asset
+ * name carries the version, which is the thing we do not know — so the release
+ * is read through the API and its asset list is matched.
+ */
+export declare function resolveLatestRelease(fetchImpl: typeof fetch): Promise<Download>;
+/**
+ * Download the extension zip for `version`, falling back to the latest release.
+ *
+ * The fallback is the normal case on a fork, on a pre-release npm install, or
+ * any time the npm package is published slightly ahead of the GitHub release —
+ * and it is reported, because installing a different version than you asked
+ * for should never be silent.
+ */
+export declare function downloadExtension(options: {
+    version: string;
+    fetchImpl?: typeof fetch;
+}): Promise<Download & {
+    buffer: Buffer;
+}>;
+export type ZipEntry = {
+    name: string;
+    data: Buffer;
+};
+/** Every file in the archive, decompressed. Directory entries are dropped. */
+export declare function readZip(buffer: Buffer): ZipEntry[];
+/**
+ * Is this a LinkedIn Toolkit extension zip?
+ *
+ * The failure this catches is mundane and common: GitHub served an HTML error
+ * page, a proxy served a login page, or the release has no asset — and the
+ * bytes get unpacked into a folder Chrome then refuses. Checking the magic
+ * number and the manifest turns that into one sentence.
+ */
+export declare function validateExtensionZip(buffer: Buffer): {
+    entries: ZipEntry[];
+    manifestVersion: string;
+    name: string;
+};
+/** Reject anything that would write outside the target folder. */
+export declare function safeEntryName(name: string): string;
+/** Write every entry under `dir`, creating the folders it needs. */
+export declare function unpackZipTo(entries: ZipEntry[], dir: string, fs?: FsLike): number;
+/**
+ * Replace `target` with `staged`, keeping a working folder at all times.
+ *
+ * Chrome loads the extension from this folder on every start, so a half-
+ * written folder is a broken extension until the user notices. The new copy is
+ * unpacked beside it and only then swapped in; if the swap fails, the previous
+ * copy goes back.
+ */
+export declare function swapIn(options: {
+    target: string;
+    staged: string;
+    fs?: FsLike;
+    now?: () => number;
+}): {
+    replaced: boolean;
+};
+export type InstallResult = Download & {
+    dir: string;
+    files: number;
+    replaced: boolean;
+    manifestVersion: string;
+};
+/** Download, check, unpack, swap. The whole of step (a) in one call. */
+export declare function installExtension(options: {
+    version: string;
+    dir: string;
+    fetchImpl?: typeof fetch;
+    fs?: FsLike;
+    now?: () => number;
+}): Promise<InstallResult>;
+/**
+ * The version of `linkedin-toolkit-mcp` that is actually running.
+ *
+ * The extension and the server are released together from one tag, so the
+ * installed package version is the right default for which zip to fetch. This
+ * reads the package's own manifest rather than a constant, so a published
+ * build can never disagree with itself about what it is.
+ */
+export declare function packageVersion(read?: (path: string) => string): string | null;
+/** Where the extension lives unless `--dir` says otherwise. */
+export declare function defaultExtensionDir(home?: string | undefined): string;
+export type Platform = 'win32' | 'darwin' | 'linux' | string;
+export type ChromeLaunch = {
+    kind: 'spawn';
+    command: string;
+    args: string[];
+} | {
+    kind: 'none';
+    reason: string;
+};
+/**
+ * How to ask Chrome to show `chrome://extensions`, if we can ask at all.
+ *
+ * Chrome ignores `chrome://` URLs handed to it on the command line in most
+ * builds — it opens a new tab page instead and says nothing. So this never
+ * reports success: it either asks and tells the user to type the URL if
+ * nothing appeared, or it does not ask and says why. Claiming a page opened
+ * when it did not is worse than not trying.
+ */
+export declare function chromeLaunch(platform: Platform, env?: NodeJS.ProcessEnv, exists?: (path: string) => boolean): ChromeLaunch;
+export declare const CLIENTS: readonly ["claude-desktop", "claude-code", "cursor", "windsurf", "vscode", "n8n", "print"];
+export type ClientId = (typeof CLIENTS)[number];
+export declare const SERVER_KEY = "linkedin-toolkit";
+/** The stdio entry every MCP client gets, in that client's spelling. */
+export declare function serverEntry(client: ClientId): Record<string, unknown>;
+export type ClientTarget = {
+    id: ClientId;
+    label: string;
+    /** `write`: we can merge into a real file. `print`: we can only show it. */
+    mode: 'write' | 'print';
+    /** The config file, when there is one. */
+    path?: string;
+    /** The object key servers hang off: `mcpServers` everywhere but VS Code. */
+    key: 'mcpServers' | 'servers';
+    /** Why this one is printed rather than written, or what to do after writing. */
+    note: string;
+};
+export type Env = {
+    platform: Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    cwd?: string;
+};
+/**
+ * Where each client keeps its MCP config, per OS.
+ *
+ * Two are project-scoped by design (`.mcp.json`, `.vscode/mcp.json`) because
+ * that is where those clients look first and where a user can see them; two
+ * are user-scoped because the client has no project scope. n8n is printed, not
+ * written: its MCP client is configured inside a workflow in the n8n UI — and
+ * on the usual Docker install the config is not even on this machine — so
+ * there is no file here to merge into.
+ */
+export declare function clientTarget(id: ClientId, context: Env): ClientTarget;
+/** The snippet a print-only client gets. */
+export declare function configSnippet(client: ClientId): string;
+export type MergeResult = {
+    /** The file to write, already serialised. */
+    contents: string;
+    /** False when the file already said exactly this. */
+    changed: boolean;
+    /** Other servers that were in the file and are still in it. */
+    kept: string[];
+};
+/**
+ * Merge our entry into an existing client config without touching anything else.
+ *
+ * A config file people have edited by hand is not ours to rewrite. Anything we
+ * cannot parse — malformed JSON, a top level that is not an object, a
+ * `mcpServers` that is not an object — is refused with the path, so the user
+ * fixes their file rather than losing it to us.
+ */
+export declare function mergeMcpConfig(options: {
+    existing: string | null;
+    key: 'mcpServers' | 'servers';
+    name?: string;
+    entry: Record<string, unknown>;
+    path?: string;
+}): MergeResult;
+/** `2026-09-18T14-22-05Z`, so backups sort and never collide on a retry. */
+export declare function backupStamp(at: number): string;
+export type WriteOutcome = {
+    path: string;
+    /** What happened: nothing needed, written, or would have been written. */
+    action: 'unchanged' | 'written' | 'dry-run';
+    backup?: string;
+    kept: string[];
+    created: boolean;
+};
+/**
+ * Write (or pretend to write) one client's config.
+ *
+ * The original is copied to `<file>.bak-<timestamp>` before it is replaced —
+ * this is somebody's editor config, and a merge bug should cost them a rename,
+ * not their other MCP servers.
+ */
+export declare function writeClientConfig(options: {
+    target: ClientTarget;
+    entry: Record<string, unknown>;
+    dryRun?: boolean;
+    fs?: FsLike;
+    now?: () => number;
+}): WriteOutcome;
+/** The three things Chrome will not let any installer do for you. */
+export declare function chromeSteps(dir: string): string[];
+/** What `lit setup` says when the extension never paired. */
+export declare function pairingTimeoutMessage(seconds: number): string;