predictor-outreach 0.0.0-stage → 0.2.0

package/dist/http.js

@@ -0,0 +1,76 @@
+import { timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+export async function serveLocalMcp(createMcp, port, localToken) {
+    if (localToken.length < 32 ||
+        /\s/u.test(localToken) ||
+        !Number.isInteger(port) ||
+        port < 1 ||
+        port > 65535)
+        throw new Error('INVALID_LOCAL_HTTP_CONFIG');
+    const allowedHosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (!allowedHosts.has(req.headers.host ?? '') ||
+            (req.headers.origin &&
+                ![`http://127.0.0.1:${port}`, `http://localhost:${port}`].includes(req.headers.origin))) {
+            res.writeHead(403).end();
+            return;
+        }
+        const supplied = Buffer.from(req.headers.authorization ?? '');
+        const expected = Buffer.from(`Bearer ${localToken}`);
+        if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
+            res.writeHead(401).end();
+            return;
+        }
+        if (url.pathname === '/healthz') {
+            res.writeHead(200, { 'content-type': 'application/json' }).end('{"ready":true}');
+            return;
+        }
+        if (url.pathname !== '/mcp' || req.method !== 'POST') {
+            res.writeHead(404).end();
+            return;
+        }
+        if (!req.headers['content-type']?.startsWith('application/json')) {
+            res.writeHead(415).end();
+            return;
+        }
+        let bytes = 0;
+        const chunks = [];
+        try {
+            for await (const chunk of req) {
+                const data = Buffer.from(chunk);
+                bytes += data.length;
+                if (bytes > 1_048_576) {
+                    res.writeHead(413).end();
+                    return;
+                }
+                chunks.push(data);
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            const mcp = createMcp();
+            const transport = new StreamableHTTPServerTransport({
+                enableJsonResponse: true,
+            });
+            res.on('close', () => {
+                void transport.close();
+                void mcp.close();
+            });
+            // SDK's HTTP callbacks include undefined while its Transport interface uses
+            // optional callbacks; the documented transport implements this interface.
+            await mcp.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch {
+            if (!res.headersSent)
+                res.writeHead(400).end('{"error":"INVALID_MCP_REQUEST"}');
+            else
+                res.end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    return server;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { OutreachClient } from './client.js';
+export { Executor } from './executor.js';
+export { Journal } from './journal.js';
+export { NodemailerSmtp, render } from './smtp.js';
+export { mailboxesFromEnv, platformConfig, shanghaiDay } from './config.js';
+export { createOutreachServer } from './server.js';
+export { serveLocalMcp } from './http.js';
+export { connect, ConnectError, CONNECT_PROMPT, CONNECT_COMPLETED } from './connect.js';
+export { savePrivateConfig, readPrivateConfig } from './private-config.js';
+export { connectionSelfCheck } from './self-check.js';
+export { DEFAULT_PLATFORM_URL } from './platform-url.js';
+export type { Campaign, Contact, Platform, Receipt } from './types.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { OutreachClient } from './client.js';
+export { Executor } from './executor.js';
+export { Journal } from './journal.js';
+export { NodemailerSmtp, render } from './smtp.js';
+export { mailboxesFromEnv, platformConfig, shanghaiDay } from './config.js';
+export { createOutreachServer } from './server.js';
+export { serveLocalMcp } from './http.js';
+export { connect, ConnectError, CONNECT_PROMPT, CONNECT_COMPLETED } from './connect.js';
+export { savePrivateConfig, readPrivateConfig } from './private-config.js';
+export { connectionSelfCheck } from './self-check.js';
+export { DEFAULT_PLATFORM_URL } from './platform-url.js';

package/dist/journal.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { type Receipt } from './types.js';
+declare const EntrySchema: z.ZodObject<{
+    batchId: z.ZodString;
+    address: z.ZodString;
+    mailbox: z.ZodString;
+    authorizationId: z.ZodString;
+    providerMessageId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        sent: "sent";
+        failed: "failed";
+        suppressed: "suppressed";
+        bounce: "bounce";
+        intent: "intent";
+    }>;
+    day: z.ZodString;
+    at: z.ZodString;
+    reported: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type JournalEntry = z.infer<typeof EntrySchema>;
+export declare class Journal {
+    readonly directory: string;
+    readonly entries: Map<string, {
+        batchId: string;
+        address: string;
+        mailbox: string;
+        authorizationId: string;
+        status: "unknown" | "sent" | "failed" | "suppressed" | "bounce" | "intent";
+        day: string;
+        at: string;
+        reported: boolean;
+        providerMessageId?: string | undefined;
+        error?: string | undefined;
+    }>;
+    private locked;
+    constructor(directory: string);
+    static key(batchId: string, address: string): string;
+    withLock<T>(operation: () => Promise<T>): Promise<T>;
+    private load;
+    append(entry: JournalEntry): Promise<void>;
+    receipt(entry: JournalEntry): Receipt;
+    daily(mailbox: string, day: string): {
+        attempts: number;
+        failures: number;
+    };
+}
+export {};

package/dist/journal.js

@@ -0,0 +1,139 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { ReceiptSchema } from './types.js';
+const EntrySchema = ReceiptSchema.extend({
+    status: z.enum(['intent', 'sent', 'failed', 'unknown', 'suppressed', 'bounce']),
+    day: z.string(),
+    at: z.string(),
+    reported: z.boolean().default(false),
+});
+export class Journal {
+    directory;
+    entries = new Map();
+    locked = false;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    static key(batchId, address) {
+        return `${batchId}:${address.toLowerCase()}`;
+    }
+    async withLock(operation) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const path = join(this.directory, 'executor.lock');
+        const token = randomUUID();
+        const acquire = async () => {
+            const file = await open(path, 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify({ pid: process.pid, token }));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        };
+        try {
+            await acquire();
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let owner;
+            try {
+                owner = JSON.parse(await readFile(path, 'utf8'));
+            }
+            catch {
+                throw new Error('JOURNAL_LOCK_NEEDS_MANUAL_REVIEW', { cause: error });
+            }
+            if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+                throw new Error('JOURNAL_LOCK_NEEDS_MANUAL_REVIEW', { cause: error });
+            try {
+                process.kill(owner.pid, 0);
+                throw new Error('EXECUTOR_ALREADY_RUNNING', { cause: error });
+            }
+            catch (probeError) {
+                if (probeError.code !== 'ESRCH')
+                    throw new Error('EXECUTOR_ALREADY_RUNNING', { cause: probeError });
+            }
+            // Renaming/removing a stale lock concurrently would permit two senders. A separate
+            // exclusive recovery lock serializes reclaim, and acquire remains exclusive.
+            const recoveryPath = join(this.directory, 'recovery.lock');
+            let recovery;
+            try {
+                recovery = await open(recoveryPath, 'wx', 0o600);
+            }
+            catch {
+                throw new Error('EXECUTOR_ALREADY_RUNNING', { cause: error });
+            }
+            try {
+                const current = JSON.parse(await readFile(path, 'utf8'));
+                if (current.token !== owner.token)
+                    throw new Error('EXECUTOR_ALREADY_RUNNING', { cause: error });
+                await rm(path);
+                await acquire();
+            }
+            finally {
+                await recovery.close();
+                await rm(recoveryPath);
+            }
+        }
+        this.locked = true;
+        try {
+            await this.load();
+            return await operation();
+        }
+        finally {
+            this.locked = false;
+            const current = JSON.parse(await readFile(path, 'utf8'));
+            if (current.token === token)
+                await rm(path);
+        }
+    }
+    async load() {
+        this.entries.clear();
+        let data;
+        try {
+            data = await readFile(join(this.directory, 'journal.jsonl'), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        if (data && !data.endsWith('\n'))
+            throw new Error('JOURNAL_INCOMPLETE_NEEDS_REVIEW');
+        for (const line of data.split('\n').filter(Boolean)) {
+            const entry = EntrySchema.parse(JSON.parse(line));
+            this.entries.set(Journal.key(entry.batchId, entry.address), entry);
+        }
+    }
+    async append(entry) {
+        if (!this.locked)
+            throw new Error('JOURNAL_LOCK_REQUIRED');
+        const safe = EntrySchema.parse(entry);
+        const file = await open(join(this.directory, 'journal.jsonl'), 'a', 0o600);
+        try {
+            await file.writeFile(`${JSON.stringify(safe)}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        this.entries.set(Journal.key(safe.batchId, safe.address), safe);
+    }
+    receipt(entry) {
+        const { day: _day, at: _at, reported: _reported, ...receipt } = entry;
+        return ReceiptSchema.parse({
+            ...receipt,
+            status: entry.status === 'intent' ? 'unknown' : entry.status,
+        });
+    }
+    daily(mailbox, day) {
+        const entries = [...this.entries.values()].filter((entry) => entry.mailbox === mailbox && entry.day === day && entry.status !== 'suppressed');
+        return {
+            attempts: entries.length,
+            failures: entries.filter((entry) => ['failed', 'unknown', 'intent', 'bounce'].includes(entry.status)).length,
+        };
+    }
+}

package/dist/main.d.ts

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

package/dist/main.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { OutreachClient } from './client.js';
+import { connect, ConnectError, CONNECT_COMPLETED } from './connect.js';
+import { journalDirectory, mailboxesFromEnv } from './config.js';
+import { Executor } from './executor.js';
+import { Journal } from './journal.js';
+import { serveLocalMcp } from './http.js';
+import { createOutreachServer } from './server.js';
+import { NodemailerSmtp } from './smtp.js';
+import { connectionSelfCheck } from './self-check.js';
+try {
+    const command = process.argv[2] ?? 'mcp';
+    if (command === 'connect') {
+        const result = await connect();
+        if (!result.ready)
+            process.exitCode = 2;
+    }
+    else {
+        const mailboxes = mailboxesFromEnv();
+        const smtp = new NodemailerSmtp();
+        if (command === 'self-check') {
+            const api = new OutreachClient();
+            const check = await connectionSelfCheck(await api.request('GET', 'status'), mailboxes, smtp);
+            process.stdout.write(`${JSON.stringify(check)}\n`);
+            if (check.ready)
+                process.stdout.write(`${CONNECT_COMPLETED}\n`);
+            else
+                process.exitCode = 2;
+        }
+        else {
+            const api = new OutreachClient();
+            const executor = new Executor(api, mailboxes, smtp, new Journal(journalDirectory()));
+            if (command === 'send') {
+                const batchId = z.string().uuid().parse(process.argv[3]);
+                process.stdout.write(`${JSON.stringify(await executor.send(batchId))}\n`);
+            }
+            else if (command === 'flush-receipts') {
+                process.stdout.write(`${JSON.stringify(await executor.flush())}\n`);
+            }
+            else if (command === 'http') {
+                await serveLocalMcp(() => createOutreachServer(api, executor), Number(process.env.OUTREACH_HTTP_PORT ?? 3457), process.env.OUTREACH_LOCAL_HTTP_TOKEN ?? '');
+                process.stderr.write('Predictor outreach MCP listening on loopback only.\n');
+            }
+            else if (command === 'mcp') {
+                await createOutreachServer(api, executor).connect(new StdioServerTransport());
+            }
+            else {
+                throw new Error('UNKNOWN_COMMAND');
+            }
+        }
+    }
+}
+catch (error) {
+    process.stderr.write(error instanceof ConnectError
+        ? `Predictor outreach connect failed (${error.code}). 授权失败后请停止，不要自动重试；可在连接管理中撤销已签发连接。\n`
+        : 'Predictor outreach operation failed. Check configuration and durable receipts locally; unknown deliveries must not be resent.\n');
+    process.exitCode = 1;
+}

package/dist/platform-url.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_PLATFORM_URL = "https://www.xhnova.com";
+export declare function platformEndpoint(platformUrl: string): {
+    baseUrl: string;
+    origin: string;
+};

package/dist/platform-url.js

@@ -0,0 +1,24 @@
+export const DEFAULT_PLATFORM_URL = 'https://www.xhnova.com';
+export function platformEndpoint(platformUrl) {
+    let url;
+    try {
+        url = new URL(platformUrl);
+    }
+    catch {
+        throw new Error('INVALID_PLATFORM_URL');
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((url.protocol !== 'https:' && !(local && url.protocol === 'http:')) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash)
+        throw new Error('INVALID_PLATFORM_URL');
+    const prefix = url.pathname.replace(/\/+$/u, '');
+    const path = prefix.endsWith('/api/outreach/v1')
+        ? prefix
+        : prefix.endsWith('/api')
+            ? `${prefix}/outreach/v1`
+            : `${prefix}/api/outreach/v1`;
+    return { baseUrl: `${url.origin}${path}`, origin: url.origin };
+}

package/dist/private-config.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    platformUrl: z.ZodString;
+    token: z.ZodString;
+}, z.core.$strict>;
+export type PrivateConfig = z.infer<typeof ConfigSchema>;
+export declare function readPrivateConfig(directory: string): PrivateConfig | undefined;
+export declare function savePrivateConfig(directory: string, input: PrivateConfig): Promise<void>;
+export {};

package/dist/private-config.js

@@ -0,0 +1,136 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { chmod, lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { platformEndpoint } from './platform-url.js';
+const ConfigSchema = z
+    .object({
+    platformUrl: z.string().max(2000),
+    token: z
+        .string()
+        .min(1)
+        .max(8192)
+        .regex(/^[^\s]+$/u),
+})
+    .strict();
+function validConfig(input) {
+    const parsed = ConfigSchema.safeParse(input);
+    if (!parsed.success)
+        throw new Error('INVALID_PRIVATE_CONFIG');
+    platformEndpoint(parsed.data.platformUrl);
+    return parsed.data;
+}
+export function readPrivateConfig(directory) {
+    try {
+        const path = join(directory, 'config.json');
+        const info = lstatSync(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 16_384)
+            throw new Error('INVALID_PRIVATE_CONFIG');
+        if (process.platform !== 'win32' && (info.mode & 0o777) !== 0o600)
+            throw new Error('PRIVATE_CONFIG_PERMISSIONS');
+        return validConfig(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        // eslint-disable-next-line preserve-caught-error -- JSON parser diagnostics may contain token bytes.
+        throw new Error('INVALID_PRIVATE_CONFIG');
+    }
+}
+/** NTFS does not encode POSIX 0600. Remove inherited grants and grant only this user. */
+async function restrictPath(path, mode) {
+    if (process.platform !== 'win32') {
+        await chmod(path, mode);
+        if (((await lstat(path)).mode & 0o777) !== mode)
+            throw new Error('PRIVATE_CONFIG_PERMISSIONS');
+        return;
+    }
+    // Windows may add explicit default-DACL grants when a file is created. A
+    // replacement DACL removes those too, instead of only removing inheritance.
+    const script = `
+$ErrorActionPreference = 'Stop'
+try {
+  $owner = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+  if ($env:OUTREACH_PRIVATE_DIRECTORY -eq '1') {
+    $acl = [System.Security.AccessControl.DirectorySecurity]::new()
+    $acl.SetSecurityDescriptorSddlForm('D:P(A;OICI;FA;;;' + $owner.Value + ')', [System.Security.AccessControl.AccessControlSections]::Access)
+    [System.IO.Directory]::SetAccessControl($env:OUTREACH_PRIVATE_PATH, $acl)
+  } else {
+    $acl = [System.Security.AccessControl.FileSecurity]::new()
+    $acl.SetSecurityDescriptorSddlForm('D:P(A;;FA;;;' + $owner.Value + ')', [System.Security.AccessControl.AccessControlSections]::Access)
+    [System.IO.File]::SetAccessControl($env:OUTREACH_PRIVATE_PATH, $acl)
+  }
+  exit 0
+} catch { exit 1 }
+`;
+    const permission = spawnSync('powershell.exe', [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-EncodedCommand',
+        Buffer.from(script, 'utf16le').toString('base64'),
+    ], {
+        env: {
+            ...process.env,
+            OUTREACH_PRIVATE_PATH: path,
+            OUTREACH_PRIVATE_DIRECTORY: mode === 0o700 ? '1' : '0',
+        },
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (permission.status !== 0)
+        throw new Error('PRIVATE_CONFIG_PERMISSIONS');
+}
+export async function savePrivateConfig(directory, input) {
+    const config = validConfig(input);
+    const target = join(directory, 'config.json');
+    const temporary = join(directory, `.config-${randomUUID()}.tmp`);
+    let created = false;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const parent = await lstat(directory);
+        if (!parent.isDirectory() || parent.isSymbolicLink())
+            throw new Error('PRIVATE_CONFIG_DIRECTORY');
+        await restrictPath(directory, 0o700);
+        try {
+            const old = await lstat(target);
+            if (!old.isFile() || old.isSymbolicLink())
+                throw new Error('INVALID_PRIVATE_CONFIG');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const file = await open(temporary, 'wx', 0o600);
+        created = true;
+        try {
+            // Secure the temporary file before writing any token bytes.
+            await restrictPath(temporary, 0o600);
+            await file.writeFile(`${JSON.stringify(config)}\n`, 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, target);
+        created = false;
+        // Flush the directory entry on filesystems that support it. Windows rename
+        // preserves the explicitly restricted file ACL instead of a POSIX mode.
+        if (process.platform !== 'win32') {
+            const parentFile = await open(directory, 'r');
+            try {
+                await parentFile.sync();
+            }
+            finally {
+                await parentFile.close();
+            }
+        }
+    }
+    catch {
+        if (created)
+            await unlink(temporary).catch(() => undefined);
+        throw new Error('PRIVATE_CONFIG_WRITE_FAILED');
+    }
+}

package/dist/self-check.d.ts

@@ -0,0 +1,15 @@
+import type { Mailbox } from './config.js';
+import type { LocalSmtp } from './smtp.js';
+export declare function assertMailboxPoolLimit(status: unknown, mailboxes: Mailbox[]): void;
+export declare function mailboxSelfCheck(status: unknown, mailboxes: Mailbox[], smtp: LocalSmtp): Promise<{
+    mailbox: string;
+    available: boolean;
+}[]>;
+export declare function connectionSelfCheck(status: unknown, mailboxes: Mailbox[], smtp: LocalSmtp): Promise<{
+    platformStatus: string;
+    mailboxes: {
+        mailbox: string;
+        available: boolean;
+    }[];
+    ready: boolean;
+}>;

package/dist/self-check.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+const PolicySchema = z.object({
+    status: z.string().optional(),
+    quota: z
+        .object({ mailboxPoolLimit: z.number().int().positive().nullable().optional() })
+        .optional(),
+});
+export function assertMailboxPoolLimit(status, mailboxes) {
+    const parsed = PolicySchema.safeParse(status);
+    if (!parsed.success)
+        throw new Error('INVALID_PLATFORM_POLICY');
+    const limit = parsed.data.quota?.mailboxPoolLimit;
+    if (limit !== null && limit !== undefined && mailboxes.length > limit)
+        throw new Error('MAILBOX_POOL_LIMIT_EXCEEDED');
+}
+export async function mailboxSelfCheck(status, mailboxes, smtp) {
+    assertMailboxPoolLimit(status, mailboxes);
+    return Promise.all(mailboxes.map(async (mailbox) => ({
+        mailbox: mailbox.user,
+        available: await smtp.verify(mailbox).catch(() => false),
+    })));
+}
+export async function connectionSelfCheck(status, mailboxes, smtp) {
+    const parsed = PolicySchema.safeParse(status);
+    if (!parsed.success || !parsed.data.status)
+        throw new Error('INVALID_PLATFORM_POLICY');
+    const health = await mailboxSelfCheck(status, mailboxes, smtp);
+    return {
+        platformStatus: parsed.data.status,
+        mailboxes: health,
+        ready: parsed.data.status === 'active' &&
+            health.length > 0 &&
+            health.every((mailbox) => mailbox.available),
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Executor } from './executor.js';
+import { type Platform } from './types.js';
+export declare function createOutreachServer(api: Platform, executor: Executor): McpServer;