@sendmux/cli 1.4.1 → 1.6.0

package/README.md

@@ -17,10 +17,11 @@ Agent-drivable command line interface for Sendmux.
 
 ## Requirements
 
+- No existing Sendmux account or API key is required to register an agent inbox.
 - npm global installs, `npx`, or a downloaded release tarball.
-- A root `smx_root_*` key for Management commands.
-- A send-capable `smx_mbx_*` key or owner-approved Sending-resource `smx_agent_*` token for Sending commands.
-- A mailbox-scoped `smx_mbx_*` key or scoped `smx_agent_*` token for Mailbox commands. Agent tokens remain limited by server-side scopes; pre-claim self-registered agent tokens do not include `email.send`.
+- Management commands require an OAuth profile with the requested permissions or a root `smx_root_*` key.
+- Sending commands require an OAuth profile with `email.send`, a send-capable `smx_mbx_*` key, or an owner-approved agent profile.
+- Mailbox commands require an OAuth profile with the requested mailbox permissions, a mailbox-scoped `smx_mbx_*` key, or a registered agent profile.
 
 ## Installation
 
@@ -30,9 +31,66 @@ npm install -g @sendmux/cli
 
 The package exposes the `sendmux` binary.
 
+## Sign in with OAuth
+
+Sign in through your browser and request only the permissions your workflow needs:
+
+```sh
+sendmux auth:login work --scope mailbox.read
+sendmux mailbox:get-connection --profile work --json
+```
+
+Repeat `--scope` for additional permissions, such as `email.send` or `domain.read`. The consent screen lets you choose the team and mailboxes. A login creates a new profile; it cannot overwrite an existing profile. Use `--no-browser` to print the authorization URL without opening it automatically; open that URL on the same computer so the loopback callback reaches the CLI.
+
+The CLI uses an authorization code with S256 PKCE and validates the callback state and issuer. Access and refresh tokens are saved in the protected local configuration file; command results and profile listings do not reveal them. API commands refresh tokens when needed. Concurrent commands share one refresh operation. If a refresh response is lost, the CLI requires a new login instead of replaying the old refresh token.
+
+Revoke the connection and remove its profile:
+
+```sh
+sendmux auth:logout work
+```
+
+If revocation fails, the profile stays available for another logout attempt. Revocation affects the connection associated with that profile.
+
+For a headless workflow that already has an access token, supply it through `SENDMUX_ACCESS_TOKEN`. Do not also set `SENDMUX_API_KEY` or pass `--api-key`. The CLI does not refresh an environment-supplied token; its issuer or your credential provider must renew it.
+
 ## Usage
 
-Create profiles for each key type before running API commands.
+Register an agent inbox and save its durable read credential in a local profile:
+
+```sh
+sendmux agent:register my-agent \
+  --mailbox-local-part my-agent \
+  --client-name "My agent" \
+  --default \
+  --json
+```
+
+The registration result never prints the credential. The profile can read and receive mail without an expiry date, unless the registration is fully revoked. Inbox readiness may take a moment; the command waits for provisioning for up to 10 minutes and can be rerun safely with the same profile.
+
+Read the inbox from any later process:
+
+```sh
+sendmux mailbox:messages:list --profile my-agent --query limit=25 --json
+```
+
+To enable sending, invite the inbox owner either during registration with `--owner-email` or afterward:
+
+```sh
+sendmux agent:invite-owner owner@example.com --profile my-agent --json
+```
+
+The owner must accept the invitation and approve sending. After approval, Sending API commands automatically exchange the durable read credential for a one-hour `email.send` token and reuse it until it approaches expiry:
+
+```sh
+sendmux sending:send \
+  --profile my-agent \
+  --idempotency-key "$IDEMPOTENCY_KEY" \
+  --body '{"from":{"email":"sender@example.com"},"to":{"email":"recipient@example.com"},"subject":"Hello","text_body":"Hello"}' \
+  --json
+```
+
+Existing Sendmux users can continue creating API-key profiles:
 
 ```sh
 sendmux profiles:set default --api-key smx_root_... --default
@@ -50,6 +108,16 @@ sendmux sending:send --profile sending --body '{"from":{"email":"sender@example.
 
 Commands reject mismatched key types before making a network request.
 
+Check the selected profile's connection without sending an email:
+
+```sh
+sendmux management:get-connection --profile default --json
+sendmux mailbox:get-connection --profile mailbox --json
+sendmux sending:get-connection --profile sending --json
+```
+
+Each command returns the team, credential, connection label, permissions, and authorised mailboxes. Mailbox connection checks do not need a mailbox selector.
+
 ## Attachments And Events
 
 Send a mailbox message with a local file in one command:
@@ -98,11 +166,12 @@ sendmux mailbox:stream-events \
 
 ## Commands
 
-The CLI includes `97` generated API operation commands:
+The CLI includes `104` generated API operation commands:
 
-- `41` Mailbox commands, including `mailbox:messages:list`, `mailbox:messages:get`, `mailbox:send-message`, and `mailbox:list-granted-mailboxes`.
-- `53` Management commands, including `management:domains:list`, `management:create-mailbox`, `management:get-spend-summary`, and `management:create-webhook`.
-- `3` Sending commands: `sending:get-open-api-spec`, `sending:send`, and `sending:send:batch`.
+- `42` Mailbox commands, including `mailbox:get-connection`, `mailbox:messages:list`, `mailbox:send-message`, and `mailbox:list-granted-mailboxes`.
+- `54` Management commands, including `management:get-connection`, `management:domains:list`, `management:create-mailbox`, and `management:create-webhook`.
+- `8` Sending commands, including `sending:get-connection`, `sending:get-open-api-spec`, `sending:send`, `sending:send:batch`, and attachment upload commands.
+- Agent onboarding commands: `agent:register` and `agent:invite-owner`.
 - Profile commands: `profiles:list`, `profiles:set`, and `profiles:show`.
 
 Use command-level help for required path, query, header, and body fields.

package/dist/agent-auth.d.ts

@@ -0,0 +1,37 @@
+import { type ActiveAgentCliProfile, type CliConfig } from "./profiles.js";
+interface RegisterAgentInput {
+    appOrigin?: string;
+    clientName?: string;
+    configDir: string;
+    makeDefault: boolean;
+    mailboxLocalPart?: string;
+    ownerEmail?: string;
+    profileName: string;
+}
+export interface SafeAgentRegistrationResult {
+    default: boolean;
+    mailbox_email: string;
+    name: string;
+    owner_invite_status?: "pending";
+    registration_id: string;
+    status: "active";
+}
+export declare function registerAgent(input: RegisterAgentInput): Promise<SafeAgentRegistrationResult>;
+export declare function inviteAgentOwner({ configDir, email, profileName, }: {
+    configDir: string;
+    email: string;
+    profileName: string;
+}): Promise<{
+    email: string;
+    status: "pending";
+}>;
+export declare function resolveAgentSendingToken({ config, configDir, profile, profileName, }: {
+    config: CliConfig;
+    configDir: string;
+    profile: ActiveAgentCliProfile;
+    profileName: string;
+}): Promise<string>;
+export declare function normaliseAppOrigin(value: string): string;
+export declare function waitForMailbox(profile: ActiveAgentCliProfile, timeoutMs?: number): Promise<void>;
+export {};
+//# sourceMappingURL=agent-auth.d.ts.map

package/dist/agent-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-auth.d.ts","sourceRoot":"","sources":["../src/agent-auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,qBAAqB,EAE1B,KAAK,SAAS,EAGf,MAAM,eAAe,CAAC;AAUvB,UAAU,kBAAkB;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAWD,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,CAAC,EAAE,SAAS,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAyGnG;AAED,wBAAsB,gBAAgB,CAAC,EACrC,SAAS,EACT,KAAK,EACL,WAAW,GACZ,EAAE;IACD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,CAiChD;AAED,wBAAsB,wBAAwB,CAAC,EAC7C,MAAM,EACN,SAAS,EACT,OAAO,EACP,WAAW,GACZ,EAAE;IACD,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2ClB;AA6DD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYxD;AAaD,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,EAC9B,SAAS,SAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/agent-auth.js

@@ -0,0 +1,348 @@
+import { randomUUID } from "node:crypto";
+import { isIP } from "node:net";
+import { clearAgentRegistrationIntent, isActiveAgentProfile, readCliConfig, reserveAgentRegistrationIntent, updateCliConfig, } from "./profiles.js";
+const DEFAULT_APP_ORIGIN = "https://app.sendmux.ai";
+const DEFAULT_SENDING_API_BASE_URL = "https://smtp.sendmux.ai/api/v1";
+const SENDING_API_RESOURCE = "https://smtp.sendmux.ai/api/v1";
+const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+const READINESS_TIMEOUT_MS = 10 * 60 * 1_000;
+const SENDING_TOKEN_SKEW_MS = 60 * 1_000;
+export async function registerAgent(input) {
+    const initialConfig = await readCliConfig(input.configDir);
+    const existing = initialConfig.profiles[input.profileName];
+    let activeProfile;
+    if (existing && isActiveAgentProfile(existing)) {
+        activeProfile = await updateCliConfig(input.configDir, (config) => {
+            const current = config.profiles[input.profileName];
+            if (!current || !isActiveAgentProfile(current)) {
+                throw new Error(`Sendmux agent profile "${input.profileName}" is not active.`);
+            }
+            assertMatchingRegistration(current, input);
+            if (input.makeDefault || !config.defaultProfile)
+                config.defaultProfile = input.profileName;
+            return current;
+        });
+        await clearAgentRegistrationIntent(input.configDir, input.profileName);
+    }
+    else {
+        const candidate = registrationIntent({ existing, input });
+        const registering = await reserveAgentRegistrationIntent(input.configDir, input.profileName, candidate);
+        assertMatchingRegistration(registering, input);
+        const persisted = await updateCliConfig(input.configDir, (config) => {
+            const current = config.profiles[input.profileName];
+            if (current && isActiveAgentProfile(current)) {
+                assertMatchingRegistration(current, input);
+                if (input.makeDefault || !config.defaultProfile)
+                    config.defaultProfile = input.profileName;
+                return { active: current };
+            }
+            if (current) {
+                if (current.type !== "agent" || current.state !== "registering") {
+                    throw new Error(`Sendmux profile "${input.profileName}" already exists and is not an agent profile.`);
+                }
+                if (current.idempotencyKey !== registering.idempotencyKey) {
+                    throw new Error(`Sendmux agent profile "${input.profileName}" belongs to a different registration request.`);
+                }
+            }
+            config.profiles[input.profileName] = registering;
+            if (input.makeDefault || !config.defaultProfile)
+                config.defaultProfile = input.profileName;
+            return { active: null };
+        });
+        if (persisted.active) {
+            activeProfile = persisted.active;
+            await clearAgentRegistrationIntent(input.configDir, input.profileName);
+        }
+        else {
+            const registration = await postJson(`${registering.authBaseUrl}/agent/identity`, {
+                headers: { "Idempotency-Key": registering.idempotencyKey },
+                body: {
+                    type: "anonymous",
+                    ...(registering.mailboxLocalPart ? { mailbox_local_part: registering.mailboxLocalPart } : {}),
+                    ...(registering.clientName ? { client_name: registering.clientName } : {}),
+                    idempotency_key: registering.idempotencyKey,
+                },
+                expectedStatuses: [200, 201],
+            });
+            assertRegistrationResponse(registration);
+            activeProfile = await updateCliConfig(input.configDir, (config) => {
+                const current = config.profiles[input.profileName];
+                if (current && isActiveAgentProfile(current)) {
+                    if (current.idempotencyKey !== registering.idempotencyKey) {
+                        throw new Error(`Sendmux agent profile "${input.profileName}" belongs to a different registration request.`);
+                    }
+                    return current;
+                }
+                if (!current ||
+                    current.type !== "agent" ||
+                    current.state !== "registering" ||
+                    current.idempotencyKey !== registering.idempotencyKey) {
+                    throw new Error(`Sendmux agent profile "${input.profileName}" belongs to a different registration request.`);
+                }
+                const activated = {
+                    ...current,
+                    accessToken: registration.access_token,
+                    mailboxEmail: registration.mailbox.email,
+                    registrationId: registration.registration_id,
+                    state: "active",
+                };
+                config.profiles[input.profileName] = activated;
+                return activated;
+            });
+            await clearAgentRegistrationIntent(input.configDir, input.profileName);
+        }
+    }
+    const reloaded = await activeAgentProfile(input.configDir, input.profileName);
+    await waitForMailbox(reloaded);
+    let ownerInviteStatus;
+    if (input.ownerEmail) {
+        await inviteAgentOwner({ configDir: input.configDir, email: input.ownerEmail, profileName: input.profileName });
+        ownerInviteStatus = "pending";
+    }
+    const finalConfig = await readCliConfig(input.configDir);
+    return {
+        default: finalConfig.defaultProfile === input.profileName,
+        mailbox_email: activeProfile.mailboxEmail,
+        name: input.profileName,
+        ...(ownerInviteStatus ? { owner_invite_status: ownerInviteStatus } : {}),
+        registration_id: activeProfile.registrationId,
+        status: "active",
+    };
+}
+export async function inviteAgentOwner({ configDir, email, profileName, }) {
+    const invitation = await updateCliConfig(configDir, (config) => {
+        const profile = activeAgentProfileFromConfig(config, profileName);
+        const existingInvite = profile.ownerInvite;
+        const idempotencyKey = existingInvite?.email.toLowerCase() === email.toLowerCase() ? existingInvite.idempotencyKey : randomUUID();
+        const updatedProfile = {
+            ...profile,
+            ownerInvite: { email, idempotencyKey, status: "dispatching" },
+        };
+        config.profiles[profileName] = updatedProfile;
+        return { idempotencyKey, profile: updatedProfile };
+    });
+    await postJson(`${invitation.profile.authBaseUrl}/agent/identity/invite`, {
+        headers: {
+            Authorization: `Bearer ${invitation.profile.accessToken}`,
+            "Idempotency-Key": invitation.idempotencyKey,
+        },
+        body: { email, idempotency_key: invitation.idempotencyKey, requested_role: "owner" },
+        expectedStatuses: [200, 202],
+    });
+    await updateCliConfig(configDir, (config) => {
+        const current = activeAgentProfileFromConfig(config, profileName);
+        if (current.ownerInvite?.idempotencyKey === invitation.idempotencyKey) {
+            config.profiles[profileName] = {
+                ...current,
+                ownerInvite: { email, idempotencyKey: invitation.idempotencyKey, status: "pending" },
+            };
+        }
+    });
+    return { email, status: "pending" };
+}
+export async function resolveAgentSendingToken({ config, configDir, profile, profileName, }) {
+    if (profile.sendingToken && Date.parse(profile.sendingToken.expiresAt) > Date.now() + SENDING_TOKEN_SKEW_MS) {
+        return profile.sendingToken.accessToken;
+    }
+    const response = await fetch(`${profile.authBaseUrl}/oauth2/token`, {
+        body: new URLSearchParams({
+            grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+            resource: SENDING_API_RESOURCE,
+            scope: "email.send",
+            subject_token: profile.accessToken,
+            subject_token_type: ACCESS_TOKEN_TYPE,
+        }),
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        method: "POST",
+    });
+    const body = await responseJson(response);
+    if (!response.ok) {
+        throw new Error(agentAuthFailureMessage(response.status, body));
+    }
+    const accessToken = requiredString(body, "access_token", "token exchange");
+    const expiresIn = body.expires_in;
+    if (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        throw new Error("Sendmux token exchange returned an invalid expiry.");
+    }
+    const updatedProfile = await updateCliConfig(configDir, (latestConfig) => {
+        const latestProfile = activeAgentProfileFromConfig(latestConfig, profileName);
+        if (latestProfile.sendingToken && Date.parse(latestProfile.sendingToken.expiresAt) > Date.now() + SENDING_TOKEN_SKEW_MS) {
+            return latestProfile;
+        }
+        const updated = {
+            ...latestProfile,
+            sendingToken: {
+                accessToken,
+                expiresAt: new Date(Date.now() + expiresIn * 1_000).toISOString(),
+            },
+        };
+        latestConfig.profiles[profileName] = updated;
+        return updated;
+    });
+    config.profiles[profileName] = updatedProfile;
+    return updatedProfile.sendingToken.accessToken;
+}
+function registrationIntent({ existing, input, }) {
+    const urls = agentUrls(input.appOrigin);
+    if (existing?.type === "agent") {
+        if (existing.state !== "registering") {
+            throw new Error(`Sendmux agent profile "${input.profileName}" is already active.`);
+        }
+        assertMatchingRegistration(existing, input);
+        return existing;
+    }
+    if (existing) {
+        throw new Error(`Sendmux profile "${input.profileName}" already exists and is not an agent profile.`);
+    }
+    return {
+        ...urls,
+        ...(input.clientName ? { clientName: input.clientName } : {}),
+        idempotencyKey: randomUUID(),
+        ...(input.mailboxLocalPart ? { mailboxLocalPart: input.mailboxLocalPart } : {}),
+        state: "registering",
+        type: "agent",
+    };
+}
+function assertMatchingRegistration(profile, input) {
+    if ((input.appOrigin !== undefined && !registrationUrlsMatch(profile, agentUrls(input.appOrigin))) ||
+        (input.clientName !== undefined && profile.clientName !== input.clientName) ||
+        (input.mailboxLocalPart !== undefined && profile.mailboxLocalPart !== input.mailboxLocalPart)) {
+        throw new Error(`Sendmux agent profile "${input.profileName}" belongs to a different registration request.`);
+    }
+}
+function registrationUrlsMatch(profile, urls) {
+    return (profile.appApiBaseUrl === urls.appApiBaseUrl &&
+        profile.authBaseUrl === urls.authBaseUrl &&
+        profile.sendingApiBaseUrl === urls.sendingApiBaseUrl);
+}
+function agentUrls(appOriginInput) {
+    const customOrigin = appOriginInput ? normaliseAppOrigin(appOriginInput) : null;
+    const appOrigin = customOrigin ?? DEFAULT_APP_ORIGIN;
+    return {
+        appApiBaseUrl: `${appOrigin}/api/v1`,
+        authBaseUrl: `${appOrigin}/agent-auth`,
+        sendingApiBaseUrl: customOrigin ? `${customOrigin}/api/v1` : DEFAULT_SENDING_API_BASE_URL,
+    };
+}
+export function normaliseAppOrigin(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error("--base-url must be an HTTP(S) origin without credentials, query, or fragment.");
+    }
+    if (url.pathname !== "/") {
+        throw new Error("--base-url must be an origin without a path.");
+    }
+    if (url.protocol === "http:" && !isLoopbackHttpOrigin(value)) {
+        throw new Error("--base-url must use HTTPS unless it is a canonical loopback origin.");
+    }
+    return url.origin;
+}
+function isLoopbackHttpOrigin(value) {
+    const authority = value.match(/^http:\/\/([^/?#]+)/i)?.[1];
+    if (!authority)
+        return false;
+    const rawHostname = authority.startsWith("[")
+        ? authority.slice(1, authority.indexOf("]"))
+        : authority.split(":", 1)[0];
+    if (!rawHostname)
+        return false;
+    if (rawHostname.toLowerCase() === "localhost" || rawHostname === "::1")
+        return true;
+    return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(rawHostname) && isIP(rawHostname) === 4 && rawHostname.split(".")[0] === "127";
+}
+export async function waitForMailbox(profile, timeoutMs = READINESS_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        const remainingBeforeFetch = deadline - Date.now();
+        if (remainingBeforeFetch <= 0)
+            throw mailboxReadinessTimeoutError();
+        let response;
+        try {
+            response = await fetch(`${profile.appApiBaseUrl}/mailbox/me`, {
+                headers: { Authorization: `Bearer ${profile.accessToken}` },
+                signal: AbortSignal.timeout(remainingBeforeFetch),
+            });
+        }
+        catch (error) {
+            if (isAbortError(error) || Date.now() >= deadline)
+                throw mailboxReadinessTimeoutError();
+            throw error;
+        }
+        if (response.ok)
+            return;
+        const body = await responseJson(response);
+        const provisioningUnavailable = response.status === 503 && (body.error === "service_unavailable" || body.error === "temporarily_unavailable");
+        if (!provisioningUnavailable) {
+            throw new Error(agentAuthFailureMessage(response.status, body));
+        }
+        const remainingBeforeRetry = deadline - Date.now();
+        if (remainingBeforeRetry <= 0)
+            throw mailboxReadinessTimeoutError();
+        const retryDelayMs = Math.min(Math.max(retryAfterSeconds(response, body) * 1_000, 1_000), remainingBeforeRetry);
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+}
+function isAbortError(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function mailboxReadinessTimeoutError() {
+    return new Error("Agent mailbox provisioning did not finish within the allowed time.");
+}
+async function activeAgentProfile(configDir, profileName) {
+    return activeAgentProfileFromConfig(await readCliConfig(configDir), profileName);
+}
+function activeAgentProfileFromConfig(config, profileName) {
+    const profile = config.profiles[profileName];
+    if (!profile || !isActiveAgentProfile(profile)) {
+        throw new Error(`Sendmux agent profile "${profileName}" is not active.`);
+    }
+    return profile;
+}
+async function postJson(url, options) {
+    const response = await fetch(url, {
+        body: JSON.stringify(options.body),
+        headers: { "Content-Type": "application/json", ...options.headers },
+        method: "POST",
+    });
+    const body = await responseJson(response);
+    if (!options.expectedStatuses.includes(response.status)) {
+        throw new Error(agentAuthFailureMessage(response.status, body));
+    }
+    return body;
+}
+async function responseJson(response) {
+    const body = await response.json().catch(() => null);
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new Error(`Sendmux agent authentication returned HTTP ${response.status} without a JSON object.`);
+    }
+    return body;
+}
+function retryAfterSeconds(response, body) {
+    const value = Number(response.headers.get("Retry-After") ?? body.retry_after ?? 10);
+    return Number.isFinite(value) && value > 0 ? value : 1;
+}
+function agentAuthFailureMessage(status, body) {
+    if (status === 503 && body.error === "authorization_pending") {
+        return "Agent sending is awaiting owner acceptance or approval.";
+    }
+    if (status === 503 && (body.error === "service_unavailable" || body.error === "temporarily_unavailable")) {
+        return "Agent mailbox provisioning did not finish within the allowed time.";
+    }
+    const description = typeof body.error_description === "string" ? body.error_description : null;
+    return description ?? `Sendmux agent authentication failed with HTTP ${status}.`;
+}
+function assertRegistrationResponse(value) {
+    requiredString(value, "access_token", "agent registration");
+    requiredString(value, "registration_id", "agent registration");
+    if (!value.mailbox || typeof value.mailbox !== "object" || typeof value.mailbox.email !== "string") {
+        throw new Error("Sendmux agent registration did not return a mailbox email.");
+    }
+}
+function requiredString(record, field, source) {
+    const value = record[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Sendmux ${source} did not return ${field}.`);
+    }
+    return value;
+}

package/dist/base-command.d.ts

@@ -5,12 +5,18 @@ export interface AuthFlags {
     "base-url"?: string;
     profile?: string;
 }
-export interface ResolvedAuth {
-    apiKey: string;
-    apiKeyKind: ApiKeyKind;
+export type ResolvedAuth = {
     baseUrl?: string;
     source: string;
-}
+} & ({
+    apiKey: string;
+    apiKeyKind: ApiKeyKind;
+    accessToken?: never;
+} | {
+    accessToken: string | (() => Promise<string>);
+    apiKey?: never;
+    apiKeyKind: "oauth";
+});
 export declare const authFlags: {
     "api-key": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     "base-url": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -20,6 +26,7 @@ export declare abstract class SendmuxCommand extends Command {
     static enableJsonFlag: boolean;
     resolveAuth(flags: AuthFlags, expectedKind: RequiredApiKeyKind): Promise<ResolvedAuth>;
     renderResult(value: unknown): unknown;
+    protected toErrorJson(error: unknown): unknown;
     renderTextResult(value: string): unknown;
     renderBinaryResult(value: ArrayBuffer | ArrayBufferView | string): unknown;
     private assertKeyKind;

package/dist/base-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-command.d.ts","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAE7C,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,SAAS;;;;CAcrB,CAAC;AAEF,8BAAsB,cAAe,SAAQ,OAAO;IAClD,MAAM,CAAC,cAAc,UAAQ;IAEvB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAmD5F,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IASrC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IASxC,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,GAAG,MAAM,GAAG,OAAO;IAa1E,OAAO,CAAC,aAAa;CA4BtB"}
+{"version":3,"file":"base-command.d.ts","sourceRoot":"","sources":["../src/base-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAE7C,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAUvB,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,CACA;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GAC/D;IAAE,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CACzF,CAAC;AAEF,eAAO,MAAM,SAAS;;;;CAcrB,CAAC;AAEF,8BAAsB,cAAe,SAAQ,OAAO;IAClD,MAAM,CAAC,cAAc,UAAQ;IAEvB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAoG5F,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IASrC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAM9C,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IASxC,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,eAAe,GAAG,MAAM,GAAG,OAAO;IAa1E,OAAO,CAAC,aAAa;CA4BtB"}

package/dist/base-command.js

@@ -1,6 +1,8 @@
 import { Command, Flags } from "@oclif/core";
 import { apiKeyKindLabel, inferApiKeyKind, isApiKeyCompatibleWithKind, } from "./key-kind.js";
-import { readCliConfig } from "./profiles.js";
+import { resolveAgentSendingToken } from "./agent-auth.js";
+import { resolveOAuthToken } from "./oauth-profile.js";
+import { isActiveAgentProfile, isAgentProfile, isOAuthProfile, readCliConfig, } from "./profiles.js";
 export const authFlags = {
     "api-key": Flags.string({
         description: "Sendmux API key. Defaults to SENDMUX_API_KEY.",
@@ -19,8 +21,22 @@ export const authFlags = {
 export class SendmuxCommand extends Command {
     static enableJsonFlag = true;
     async resolveAuth(flags, expectedKind) {
-        const envApiKey = process.env.SENDMUX_API_KEY;
-        const envBaseUrl = process.env.SENDMUX_BASE_URL;
+        const envApiKey = process.env.SENDMUX_API_KEY || undefined;
+        const accessToken = process.env.SENDMUX_ACCESS_TOKEN || undefined;
+        const envBaseUrl = process.env.SENDMUX_BASE_URL || undefined;
+        const envProfile = process.env.SENDMUX_PROFILE || undefined;
+        if (accessToken && (flags["api-key"] || envApiKey)) {
+            this.error("Provide exactly one of an API key or SENDMUX_ACCESS_TOKEN.", { exit: 2 });
+        }
+        if (accessToken) {
+            const baseUrl = flags["base-url"] ?? envBaseUrl;
+            return {
+                accessToken,
+                apiKeyKind: "oauth",
+                source: "SENDMUX_ACCESS_TOKEN",
+                ...(baseUrl ? { baseUrl } : {}),
+            };
+        }
         if (flags["api-key"] || envApiKey) {
             const apiKey = flags["api-key"] ?? envApiKey;
             if (!apiKey) {
@@ -38,7 +54,7 @@ export class SendmuxCommand extends Command {
             return this.assertKeyKind(input);
         }
         const config = await readCliConfig(this.config.configDir);
-        const profileName = flags.profile ?? process.env.SENDMUX_PROFILE ?? config.defaultProfile;
+        const profileName = flags.profile ?? envProfile ?? config.defaultProfile;
         if (!profileName) {
             this.error("No Sendmux profile configured. Run `sendmux profiles:set <name> --api-key <key> --default` or pass --api-key.", {
                 exit: 2,
@@ -50,6 +66,36 @@ export class SendmuxCommand extends Command {
                 exit: 2,
             });
         }
+        if (isOAuthProfile(profile)) {
+            const baseUrl = flags["base-url"] ?? envBaseUrl;
+            return { accessToken: () => resolveOAuthToken(this.config.configDir, profileName), apiKeyKind: "oauth", source: `OAuth profile "${profileName}"`, ...(baseUrl ? { baseUrl } : {}) };
+        }
+        if (isAgentProfile(profile)) {
+            if (!isActiveAgentProfile(profile)) {
+                this.error(`Sendmux agent profile "${profileName}" has not finished registration. Re-run \`sendmux agent:register ${profileName}\`.`, {
+                    exit: 2,
+                });
+            }
+            if (expectedKind === "root") {
+                this.error(`Command requires a root API key, but profile "${profileName}" is an agent profile.`, { exit: 2 });
+            }
+            const apiKey = expectedKind === "sending"
+                ? await resolveAgentSendingToken({
+                    config,
+                    configDir: this.config.configDir,
+                    profile,
+                    profileName,
+                })
+                : profile.accessToken;
+            const profileBaseUrl = expectedKind === "sending" ? profile.sendingApiBaseUrl : profile.appApiBaseUrl;
+            const baseUrl = flags["base-url"] ?? envBaseUrl ?? profileBaseUrl;
+            return this.assertKeyKind({
+                apiKey,
+                baseUrl,
+                expectedKind,
+                source: `agent profile "${profileName}"`,
+            });
+        }
         const baseUrl = flags["base-url"] ?? envBaseUrl ?? profile.baseUrl;
         const input = {
             apiKey: profile.apiKey,
@@ -68,6 +114,11 @@ export class SendmuxCommand extends Command {
         this.log(JSON.stringify(value, null, 2));
         return value;
     }
+    toErrorJson(error) {
+        return {
+            error: error instanceof Error ? { ...error, message: error.message, name: error.name } : error,
+        };
+    }
     renderTextResult(value) {
         if (this.jsonEnabled()) {
             return { text: value };

package/dist/commands/agent/invite-owner.d.ts

@@ -0,0 +1,12 @@
+import { SendmuxCommand } from "../../base-command.js";
+export default class AgentInviteOwner extends SendmuxCommand {
+    static args: {
+        email: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static flags: {
+        profile: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}
+//# sourceMappingURL=invite-owner.d.ts.map

package/dist/commands/agent/invite-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite-owner.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/invite-owner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,CAAC,OAAO,OAAO,gBAAiB,SAAQ,cAAc;IAC1D,MAAM,CAAC,IAAI;;MAKT;IACF,MAAM,CAAC,WAAW,SAA4D;IAC9E,MAAM,CAAC,KAAK;;MAMV;IAEI,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC;CAkB9B"}