@agentisend/sdk-node 0.1.0

package/dist/cli/doctor.js

@@ -0,0 +1,161 @@
+function messageOf(err) {
+    const anyErr = err;
+    return anyErr.message ?? String(err);
+}
+export async function runDoctor(input) {
+    const checks = [];
+    if (!input.client) {
+        checks.push({
+            name: 'credentials',
+            ok: false,
+            detail: `No API key for profile "${input.profile}".`,
+            fix: `Set AGENTISEND_API_KEY, or save one with: agentisend profile set ${input.profile} --api-key as_… (stored in ${input.configPath}).`,
+        });
+        return {
+            ok: false,
+            base_url: input.baseUrl,
+            profile: input.profile,
+            key_source: input.keySource,
+            checks,
+        };
+    }
+    checks.push({
+        name: 'credentials',
+        ok: true,
+        detail: `Key from ${input.keySource}, profile "${input.profile}".`,
+    });
+    // 1. Can we reach it at all? /status needs no auth, so a failure here is
+    //    the network or the URL, never the key — worth separating.
+    try {
+        const status = await input.client.status();
+        checks.push({
+            name: 'reachable',
+            ok: true,
+            detail: `${input.baseUrl} responded (${JSON.stringify(status).slice(0, 60)}).`,
+        });
+    }
+    catch (err) {
+        checks.push({
+            name: 'reachable',
+            ok: false,
+            detail: `Could not reach ${input.baseUrl}: ${messageOf(err)}`,
+            fix: 'Check the base URL and your network. Nothing below could be tested.',
+        });
+        return {
+            ok: false,
+            base_url: input.baseUrl,
+            profile: input.profile,
+            key_source: input.keySource,
+            checks,
+        };
+    }
+    // 2. Does the key authenticate, and is it stopped?
+    try {
+        const keys = await input.client.limits.list();
+        const paused = keys.data.filter((row) => row.paused);
+        checks.push({
+            name: 'key',
+            ok: true,
+            detail: `Authenticated. ${String(keys.data.length)} key(s) on this account.`,
+        });
+        checks.push({
+            name: 'kill switch',
+            ok: paused.length === 0,
+            detail: paused.length === 0
+                ? 'No key is paused.'
+                : `${String(paused.length)} key(s) paused: ${paused.map((row) => row.api_key_id).join(', ')}.`,
+            ...(paused.length === 0
+                ? {}
+                : {
+                    fix: 'A person resumes a key: POST /limits/keys/:id/resume, or the Agents screen in the console.',
+                }),
+        });
+        const withBudget = keys.data.filter((row) => row.budget_per_period !== null);
+        const exhausted = withBudget.filter((row) => (row.budget_per_period ?? 0) - row.consumed_in_period <= 0);
+        checks.push({
+            name: 'budget',
+            ok: exhausted.length === 0,
+            detail: withBudget.length === 0
+                ? 'No key has a budget set — sending is metered but not capped.'
+                : `${String(withBudget.length)} key(s) budgeted; ${String(exhausted.length)} exhausted.`,
+            ...(exhausted.length === 0
+                ? {}
+                : { fix: 'Raise the budget (PATCH /limits/keys/:id) or wait for the period to reset.' }),
+        });
+    }
+    catch (err) {
+        const code = err.code;
+        checks.push({
+            name: 'key',
+            ok: false,
+            detail: `The key was refused: ${messageOf(err)}`,
+            fix: code === 'invalid_api_key'
+                ? 'The key is wrong or revoked. Create another with POST /api-keys.'
+                : 'Check the key has limits:read — doctor reads budgets and the kill switch.',
+        });
+    }
+    // 3. Can anything actually be sent from here?
+    try {
+        const domains = await input.client.domains.list();
+        const verified = domains.data.filter((row) => row.status === 'verified');
+        checks.push({
+            name: 'domains',
+            ok: verified.length > 0,
+            detail: verified.length > 0
+                ? `Can send from: ${verified.map((row) => row.name).join(', ')}.`
+                : `No verified domain (${String(domains.data.length)} registered). Every send will be refused.`,
+            ...(verified.length > 0
+                ? {}
+                : {
+                    fix: 'Publish the DNS records from GET /domains/:id, then POST /domains/:id/verify.',
+                }),
+        });
+    }
+    catch (err) {
+        checks.push({
+            name: 'domains',
+            ok: false,
+            detail: `Could not read domains: ${messageOf(err)}`,
+            fix: 'The key needs domains:read to answer this.',
+        });
+    }
+    // 4. Standing, because a throttled account explains slow sends that look
+    //    like a bug in the caller's code.
+    try {
+        const standing = await input.client.trust.standing();
+        checks.push({
+            name: 'trust',
+            ok: standing.state === 'ok' || standing.state === 'warning',
+            detail: `Standing: ${standing.state}${standing.reasons.length > 0 ? ` (${standing.reasons.join('; ')})` : ''}.`,
+            ...(standing.state === 'ok'
+                ? {}
+                : { fix: 'GET /trust/standing explains each reason. POST /trust/appeal asks a human to look.' }),
+        });
+    }
+    catch {
+        // trust:read is optional for a sending-only key; not having it is not a
+        // fault, so this check simply does not appear.
+    }
+    return {
+        ok: checks.every((check) => check.ok),
+        base_url: input.baseUrl,
+        profile: input.profile,
+        key_source: input.keySource,
+        checks,
+    };
+}
+export function renderDoctor(report) {
+    const lines = [
+        `Profile: ${report.profile}  ·  Key: ${report.key_source}  ·  API: ${report.base_url}`,
+        '',
+    ];
+    for (const check of report.checks) {
+        lines.push(`${check.ok ? 'ok  ' : 'FAIL'}  ${check.name}: ${check.detail}`);
+        if (check.fix)
+            lines.push(`      → ${check.fix}`);
+    }
+    lines.push('');
+    lines.push(report.ok ? 'Everything checks out.' : 'Something above needs attention.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/listen.d.ts

@@ -0,0 +1,28 @@
+/** Headers a delivery carries that the receiving app must see unchanged. */
+export declare const FORWARDED_HEADERS: string[];
+export interface ListenEvent {
+    verified: boolean;
+    event_id: string | null;
+    event_type: string | null;
+    forwarded: boolean;
+    /** Status the receiving app returned, when we got that far. */
+    forward_status?: number;
+    reason?: string;
+}
+export interface ListenOptions {
+    secret: string;
+    /** Where to forward verified deliveries. Omit to verify and report only. */
+    forwardTo?: string | undefined;
+    port?: number;
+    host?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    onEvent?: (event: ListenEvent) => void;
+    /** Injectable clock for the signature tolerance window. */
+    nowSeconds?: () => number;
+}
+export interface RunningListener {
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startWebhookListener(options: ListenOptions): Promise<RunningListener>;

package/dist/cli/listen.js

@@ -0,0 +1,140 @@
+/**
+ * M4.16 — `agentisend webhooks listen --forward-to http://localhost:3000/hook`.
+ *
+ * The one webhook feature developers name, and what it is for is the loop:
+ * point a tunnel (or the API itself, in dev) at this listener, and it verifies
+ * every delivery against the endpoint secret and forwards the ones that pass to
+ * the app being written — with the SAME headers and the SAME bytes, so the
+ * app's own verification sees exactly what production will send it.
+ *
+ * Two rules make it worth trusting:
+ *   1. It forwards the RAW body, byte for byte. A parse-and-re-serialise round
+ *      trip changes key order and whitespace, which changes the HMAC, and the
+ *      app then fails to verify a delivery that was in fact genuine.
+ *   2. A delivery that does NOT verify is refused and never forwarded. A local
+ *      relay that forwards anything is a way to inject events into an app that
+ *      believes signatures protect it.
+ */
+import { createServer } from 'node:http';
+import { EVENT_ID_HEADER, EVENT_TYPE_HEADER, REPLAY_HEADER, SIGNATURE_HEADER, SVIX_ID_HEADER, SVIX_SIGNATURE_HEADER, SVIX_TIMESTAMP_HEADER, TIMESTAMP_HEADER, verifyWebhookSignature, } from '../webhook-signing.js';
+/** Headers a delivery carries that the receiving app must see unchanged. */
+export const FORWARDED_HEADERS = [
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    EVENT_ID_HEADER,
+    EVENT_TYPE_HEADER,
+    REPLAY_HEADER,
+    SVIX_ID_HEADER,
+    SVIX_TIMESTAMP_HEADER,
+    SVIX_SIGNATURE_HEADER,
+    'content-type',
+];
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function headerOf(req, name) {
+    const value = req.headers[name];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+export async function startWebhookListener(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const handler = async (req, res) => {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Only POST deliveries are accepted here.' }));
+            return;
+        }
+        const body = await readBody(req);
+        const signature = headerOf(req, SIGNATURE_HEADER);
+        const eventId = headerOf(req, EVENT_ID_HEADER);
+        const eventType = headerOf(req, EVENT_TYPE_HEADER);
+        const verified = signature !== null &&
+            verifyWebhookSignature(options.secret, signature, body, {
+                ...(options.nowSeconds ? { nowSeconds: options.nowSeconds() } : {}),
+            });
+        if (!verified) {
+            // Refused, not forwarded. The app behind this must never receive
+            // something this listener could not prove came from AgentiSend.
+            options.onEvent?.({
+                verified: false,
+                event_id: eventId,
+                event_type: eventType,
+                forwarded: false,
+                reason: signature === null ? 'no signature header' : 'signature did not verify',
+            });
+            res.writeHead(400, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                error: {
+                    code: 'invalid_signature',
+                    message: 'This delivery did not verify against the endpoint secret, so it was dropped.',
+                    fix: 'Check that --secret is the secret for THIS endpoint. It is shown once, when the endpoint is created.',
+                },
+            }));
+            return;
+        }
+        if (!options.forwardTo) {
+            options.onEvent?.({ verified: true, event_id: eventId, event_type: eventType, forwarded: false });
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ verified: true }));
+            return;
+        }
+        // Same headers, same bytes: what the app verifies here is what it will
+        // verify in production.
+        const headers = {};
+        for (const name of FORWARDED_HEADERS) {
+            const value = headerOf(req, name);
+            if (value !== null)
+                headers[name] = value;
+        }
+        try {
+            const forwarded = await fetchImpl(options.forwardTo, { method: 'POST', headers, body });
+            options.onEvent?.({
+                verified: true,
+                event_id: eventId,
+                event_type: eventType,
+                forwarded: true,
+                forward_status: forwarded.status,
+            });
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ verified: true, forwarded_status: forwarded.status }));
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            options.onEvent?.({
+                verified: true,
+                event_id: eventId,
+                event_type: eventType,
+                forwarded: false,
+                reason: detail,
+            });
+            // 500 back to AgentiSend so the delivery is retried rather than
+            // recorded as delivered while the local app was down.
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: 'forward_failed', message: detail } }));
+        }
+    };
+    const server = createServer((req, res) => {
+        void handler(req, res).catch(() => {
+            res.writeHead(500).end();
+        });
+    });
+    await new Promise((resolve) => {
+        server.listen(options.port ?? 0, options.host ?? '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address !== null ? address.port : 0;
+    return {
+        port,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+        }),
+    };
+}
+//# sourceMappingURL=listen.js.map

package/dist/cli/listen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen.js","sourceRoot":"","sources":["../../src/cli/listen.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts

@@ -0,0 +1,14 @@
+import { AgentiSend } from '../client.js';
+export interface RunContext {
+    argv: string[];
+    env?: NodeJS.ProcessEnv;
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+    isTty?: boolean;
+    /** Injected in tests; the binary passes nothing and gets the real one. */
+    clientFactory?: (apiKey: string, baseUrl?: string) => AgentiSend;
+    readStdin?: () => string;
+    /** Test hook: keeps `receiving listen` from looping forever. */
+    now?: () => Date;
+}
+export declare function run(ctx: RunContext): Promise<number>;