primcli 1.63.0 → 1.65.0

package/README.md

@@ -324,6 +324,23 @@ still goes out, and different replies to the same email are separate sends. To
 retry an uncertain send after the window, pass the key it reported with
 `--idempotency-key`.
 
+When a send is answered with an earlier one, nothing goes out and the stderr
+notice says which send answered it and why:
+
+| Why | Notice |
+|---|---|
+| The same content inside the five-minute window, with no key of your own | `Not sent: identical to <id> sent 42s ago (status delivered). Pass --idempotency-key with a new key to send again.` |
+| A key you passed that was already used | `Not sent: idempotency key <key> was already used for <id> sent 3h ago (status delivered). A key you pass never expires. Use a different key only for a different message.` |
+| A Function sending again for the email or event that invoked it | `Not sent: this Function already sent this message as <id> sent 2m ago (status delivered), for the same email or event that invoked it. A Function that runs again for one trigger sends once.` |
+| A reply with no key to an email that already has a reply | `Not sent: the email already has a reply, <id> sent 5m ago (status delivered). Pass an idempotency key to send another reply.` |
+
+The notice goes to stderr only, so stdout stays parseable. With `--json` it is
+the envelope's `outcome_message`, and `sent.idempotency` carries the same facts
+as fields (`key_source`, `original_sent_email_id`, `original_created_at`,
+`window_seconds`). The outcome is `already_sent` and the exit code is 0 in every
+case. An API response without the `idempotency` object gets the general notice,
+`Already sent: this exact message went out earlier (...). Nothing new was sent.`
+
 Without `--json`, `send` and `reply` keep printing the send record on stdout exactly
 as before and add a one-line stderr summary such as `Reply sent (queued for
 delivery, id X). Do not resend.` Before sending, `primitive reply` (and
@@ -1036,7 +1053,13 @@ It gives the session an address once, named `<runtime>-<repository>`, using the
 saved member login, and only re-verifies on resume; a session whose agent was
 disconnected or removed never gets a second address. The SessionEnd hook runs
 `primitive agent session-end`, which disconnects only agents that
-`session-register` created. The end is recorded first, so a registration still
+`session-register` created, and only while the session's profile still holds
+that exact credential: an agent later connected into the same profile (for
+example with `primitive agent connect`) is left connected, and only the
+registered agent's own receive hooks are removed. Claude reports the same
+SessionEnd for a restart, a switch to another session and a real exit, so the
+hook waits five minutes before disconnecting, and a start of the same session
+within that time cancels the end. The end is recorded first, so a registration still
 running disconnects the agent it creates; when the local credential is gone it
 revokes by address with the member login, and an unconfirmed disconnect is
 reported as `disconnect_pending` and retried by `machine doctor --fix`. Both always exit 0 and finish slow work in the

package/dist/{api-command-CDjvGDQS.js → api-command-0u5Qd_a-.js}

@@ -1,4 +1,4 @@
-import { b as __exportAll } from "./repeats-x4QM2yoG-DTpqXyRo.js";
+import { S as __exportAll, _ as WEBHOOK_EVENT_TYPES, g as SENT_EMAIL_EVENT_TYPES } from "./repeats-BL7ZC-_6-Dzangtkf.js";
 import { C as resolveCliAuth, F as agentProfilesDirectory, G as createClient, H as requireDefaultLoginProfile, K as createConfig, N as agentProfileDirectory, R as loadConnectedAgentProfile, S as normalizeApiBaseUrl, T as saveSignupCredentials, W as PrimitiveApiClient, _ as deleteCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, j as AGENT_PROFILE_ENV, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveCliCredentials, x as loadCliCredentials, y as detectPrimitiveKeyEnvMisname } from "./cli-config-DMszFbGn.js";
 import { h as writeMailJson, m as withMailLock, p as syncMailDirectory, u as privateMailPermissions } from "./shared-mail-files-MwlVE90c.js";
 import { Command, Errors, Flags } from "@oclif/core";
@@ -1549,8 +1549,12 @@ const updateRoute = (options) => (options.client ?? client).patch({
 /**
 * List webhook deliveries
 *
-* Returns a paginated list of webhook delivery attempts. Each delivery
-* includes a nested `email` object with sender, recipient, and subject.
+* Returns a paginated list of webhook delivery attempts, newest first.
+* A delivery of an inbound email includes a nested `email` object with
+* sender, recipient, and subject. A delivery of an opt-in
+* `sent_email.*` event has `email_id` and `email` set to null and
+* `sent_email_id` set to the send it is about. Filter by `event_type`
+* and `sent_email_id` to find the deliveries of one send.
 *
 */
 const listDeliveries = (options) => (options?.client ?? client).get({
@@ -1564,11 +1568,15 @@ const listDeliveries = (options) => (options?.client ?? client).get({
 /**
 * Replay a webhook delivery
 *
-* Re-sends the stored webhook payload from a previous delivery attempt.
-* If the original endpoint is still active, it is targeted. If the
-* original endpoint was deleted, the oldest active endpoint is used.
-* Deactivated endpoints cannot be replayed to. Rate limited per-org,
-* sharing an org-wide budget with email replays.
+* Re-sends a previous delivery to its original endpoint. If that
+* endpoint was deleted or deactivated, the replay is rejected.
+* Supports inbound email deliveries and `sent_email.*` deliveries.
+* An inbound email delivery is replayed with its original stored
+* payload and event id. A `sent_email.*` delivery is replayed with the
+* same event id but a payload rebuilt from the send as it is now; it
+* is rejected if the send was deleted or the endpoint is no longer an
+* active http endpoint. Rate limited per-org, sharing an org-wide
+* budget with email replays.
 *
 */
 const replayDelivery = (options) => (options.client ?? client).post({
@@ -3701,6 +3709,79 @@ function ensureSearchReportsAutomated(apiClient) {
 	return probe;
 }
 //#endregion
+//#region src/oclif/endpoint-event-types.ts
+const EVENT_TYPES_FLAG_OPERATIONS = /* @__PURE__ */ new Set(["createEndpoint", "updateEndpoint"]);
+const EVENT_TYPES_FLAG_DESCRIPTION = "Event types this endpoint subscribes to, comma separated or repeated (sets rules.event_types). Omitting the subscription means every event type except the opt-in sent_email.* events, which an endpoint receives only when it lists them; sent_email.* expands to all four. Keep email.received in the list if the endpoint also handles inbound mail. On update, the endpoint's other rules are kept.";
+const SENT_EMAIL_WILDCARD = "sent_email.*";
+const KNOWN_EVENT_TYPES = new Set(WEBHOOK_EVENT_TYPES);
+var EventTypesFlagError = class extends Error {};
+/**
+* Turn the raw `--event-types` values into the list to store: split on
+* commas, trim, expand `sent_email.*`, and drop duplicates while keeping the
+* order the caller gave.
+*/
+function parseEventTypesFlag(values) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of values) for (const raw of value.split(",")) {
+		const name = raw.trim();
+		if (name === "") continue;
+		const names = name === SENT_EMAIL_WILDCARD ? [...SENT_EMAIL_EVENT_TYPES] : [name];
+		for (const entry of names) {
+			if (seen.has(entry)) continue;
+			seen.add(entry);
+			out.push(entry);
+		}
+	}
+	if (out.length === 0) throw new EventTypesFlagError("--event-types needs at least one event type. To receive every event type except the opt-in sent_email.* events, omit the subscription instead.");
+	if (out.length > 50) throw new EventTypesFlagError(`--event-types accepts at most 50 event types (got ${out.length}).`);
+	return out;
+}
+/** The names in `eventTypes` this CLI does not recognise. */
+function unknownEventTypes(eventTypes) {
+	return eventTypes.filter((name) => !KNOWN_EVENT_TYPES.has(name));
+}
+function unknownEventTypesWarning(unknown) {
+	return `Warning: ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not an event type this CLI knows. Subscriptions match exact names, so a misspelled name receives nothing. Continuing; newer event types may not be known to this CLI yet.\n`;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* The rules an update starts from: the endpoint's current rules, read from
+* the endpoint list. Throws when the endpoint cannot be found, so an update
+* never replaces rules it could not read.
+*/
+async function currentEndpointRules(endpointId, listEndpoints) {
+	const response = await listEndpoints();
+	if (response.error) throw new EventTypesFlagError("Could not read the endpoint's current rules to keep them. Retry, or pass the full rules with --raw-body.");
+	const row = (response.data?.data ?? []).find((endpoint) => endpoint.id === endpointId);
+	if (!row) throw new EventTypesFlagError(`No endpoint ${endpointId} is visible to this credential, so its rules cannot be updated.`);
+	return isPlainObject(row.rules) ? row.rules : {};
+}
+/**
+* Put `eventTypes` in the request body's `rules.event_types`, on top of
+* `baseRules` (rules the caller passed in the body win over `baseRules`).
+*/
+function withEventTypes(body, eventTypes, baseRules = {}) {
+	if (body !== void 0 && !isPlainObject(body)) throw new EventTypesFlagError("--raw-body must be a JSON object when also passing --event-types.");
+	const current = body ?? {};
+	if (current.rules !== void 0 && !isPlainObject(current.rules)) throw new EventTypesFlagError("rules in --raw-body must be a JSON object when also passing --event-types.");
+	const explicitRules = current.rules ?? {};
+	return {
+		...current,
+		rules: {
+			...baseRules,
+			...explicitRules,
+			event_types: [...eventTypes]
+		}
+	};
+}
+/** True when the caller already passed `rules` in the request body. */
+function bodyHasRules(body) {
+	return isPlainObject(body) && body.rules !== void 0;
+}
+//#endregion
 //#region src/oclif/endpoints-test-redirect.ts
 async function detectFunctionEndpoint(endpointId, listEndpoints) {
 	let response;
@@ -3813,22 +3894,93 @@ function withFlagSuggestion(error, valid) {
 //#region src/oclif/idempotent-replay-banner.ts
 /**
 * If `data` carries `idempotent_replay: true`, write a stderr notice
-* that the message already went out and nothing new was sent.
-* Otherwise no-op.
-*
-* The notice deliberately gives no advice on how to force a fresh
-* copy. Whoever sees a replay has already sent this message; telling
-* them to vary the content is an instruction to double-send.
+* that nothing new was sent and why. Otherwise no-op.
 */
 function writeIdempotentReplayBannerIfReplay(data, options) {
 	if (!isReplay(data)) return;
-	options.write(`${formatAlreadySentNotice(data)}\n`);
+	const { write, ...notice } = options;
+	write(`${formatAlreadySentNotice(data, notice)}\n`);
 }
 function isReplay(data) {
 	if (data === null || typeof data !== "object") return false;
 	return data.idempotent_replay === true;
 }
-function formatAlreadySentNotice(sent) {
+function nonEmptyString(value) {
+	return typeof value === "string" && value ? value : null;
+}
+/**
+* Read the API's `idempotency` object. Null when it is absent or names
+* a key source this CLI does not know, so the general notice is used
+* and nothing is claimed about a case it cannot describe.
+*/
+function readReplayDetail(sent, keyOrigin) {
+	const raw = sent.idempotency;
+	if (raw === null || typeof raw !== "object") return null;
+	const object = raw;
+	const source = object.key_source;
+	let kind;
+	if (sent.dedup_reason === "parent_already_replied") kind = "parent_already_replied";
+	else if (source === "auto_content" || source === "function_trigger") kind = source;
+	else if (source === "explicit") kind = keyOrigin === "cli_derived" ? "auto_content" : "explicit";
+	else return null;
+	return {
+		kind,
+		originalId: nonEmptyString(object.original_sent_email_id) ?? nonEmptyString(sent.id),
+		originalCreatedAt: nonEmptyString(object.original_created_at)
+	};
+}
+/** "12s ago", "4m ago", "3h ago", "9d ago"; null when the time is unusable. */
+function formatReplayAge(createdAt, now) {
+	if (createdAt === null) return null;
+	const created = Date.parse(createdAt);
+	if (Number.isNaN(created)) return null;
+	const seconds = Math.max(0, Math.round((now - created) / 1e3));
+	if (seconds < 120) return `${seconds}s ago`;
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 120) return `${minutes}m ago`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 48) return `${hours}h ago`;
+	return `${Math.round(hours / 24)}d ago`;
+}
+function statusSuffix(sent) {
+	const status = nonEmptyString(sent.status);
+	const deliveryStatus = nonEmptyString(sent.delivery_status);
+	const details = [];
+	if (status) details.push(`status ${status}`);
+	if (deliveryStatus && deliveryStatus !== status) details.push(`delivery status ${deliveryStatus}`);
+	return details.length > 0 ? ` (${details.join(", ")})` : "";
+}
+function formatSpecificNotice(sent, detail, options) {
+	const age = formatReplayAge(detail.originalCreatedAt, options.now ?? Date.now());
+	const when = age ? ` sent ${age}` : "";
+	const id = detail.originalId ?? "an earlier send";
+	const state = statusSuffix(sent);
+	const advise = options.advise !== false;
+	const keyHint = options.keyHint ?? "an idempotency key";
+	switch (detail.kind) {
+		case "auto_content": return `Not sent: identical to ${id}${when}${state}.${advise ? ` Pass ${keyHint} to send again.` : ""}`;
+		case "explicit": {
+			const key = nonEmptyString(sent.client_idempotency_key);
+			return `Not sent: ${key ? `idempotency key ${key}` : "this idempotency key"} was already used for ${id}${when}${state}. A key you pass never expires.${advise ? " Use a different key only for a different message." : ""}`;
+		}
+		case "function_trigger": return `Not sent: this Function already sent this message as ${id}${when}${state}, for the same email or event that invoked it. A Function that runs again for one trigger sends once.`;
+		case "parent_already_replied": return `Not sent: the email already has a reply, ${id}${when}${state}.${advise ? ` Pass ${keyHint} to send another reply.` : ""}`;
+	}
+}
+/**
+* The notice for a send that was answered with an existing send. Worded
+* from the API's `idempotency` object when the response carries one;
+* the general "already sent" notice otherwise.
+*
+* The advice never says to change the message. Whoever sees this has a
+* send on record already, and varying the content to get past it is how
+* a retry becomes a double send. Sending the same thing again on
+* purpose is a different request, and an idempotency key is how the API
+* is told so.
+*/
+function formatAlreadySentNotice(sent, options = {}) {
+	const detail = readReplayDetail(sent, options.keyOrigin ?? "caller");
+	if (detail) return formatSpecificNotice(sent, detail, options);
 	const details = [];
 	if (typeof sent.id === "string" && sent.id) details.push(`sent id ${sent.id}`);
 	const status = typeof sent.status === "string" && sent.status ? sent.status : null;
@@ -4297,7 +4449,10 @@ function reportSendCommandResult(params) {
 			errorPayload = { message: "The API returned no send record." };
 		} else {
 			outcome = successfulSendOutcome(sent);
-			outcomeMessage = outcome === "not_sent" || outcome === "uncertain" ? formatSendRecordFailureSummary(params.noun, outcome, sent) : outcome === "already_sent" ? formatAlreadySentNotice(sent) : formatSentSummary(params.noun, sent);
+			outcomeMessage = outcome === "not_sent" || outcome === "uncertain" ? formatSendRecordFailureSummary(params.noun, outcome, sent) : outcome === "already_sent" ? formatAlreadySentNotice(sent, {
+				keyOrigin: params.idempotencyKeyOrigin ?? "caller",
+				keyHint: "--idempotency-key with a new key"
+			}) : formatSentSummary(params.noun, sent);
 		}
 		if (!params.json) params.writeStderr(`${outcomeMessage}\n`);
 	}
@@ -5144,7 +5299,7 @@ function savedConnectedProfiles(configDir, exclude) {
 */
 async function otherProfiles(configDir, session, current) {
 	if (session) try {
-		const { connectedProfilesForSession } = await import("./machine-session-NjXIXTRX.js").then((n) => n.s);
+		const { connectedProfilesForSession } = await import("./machine-session-Bmv7ZOQh.js").then((n) => n.s);
 		return {
 			inSession: true,
 			profiles: connectedProfilesForSession(configDir, session, current)
@@ -5751,7 +5906,18 @@ function buildFlags(operation) {
 			flags[name] = bodyFieldFlag(field, aliasesForOperation?.[field.name]);
 			bodyFieldFlagToProperty.set(name, field.name);
 		}
+		const extraFlags = OPERATION_EXTRA_BODY_FLAGS[operation.sdkName] ?? {};
+		for (const [name, extra] of Object.entries(extraFlags)) {
+			if (RESERVED_FLAG_NAMES.has(name)) continue;
+			if (flags[name] !== void 0) continue;
+			flags[name] = Flags.boolean({ description: extra.description });
+			bodyFieldFlagToProperty.set(name, extra.property);
+		}
 	}
+	if (EVENT_TYPES_FLAG_OPERATIONS.has(operation.sdkName)) flags["event-types"] = Flags.string({
+		description: EVENT_TYPES_FLAG_DESCRIPTION,
+		multiple: true
+	});
 	if (operation.binaryResponse) flags.output = Flags.string({ description: "Write binary response bytes to a file" });
 	if (ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName)) flags.wait = Flags.boolean({
 		allowNo: true,
@@ -5772,6 +5938,18 @@ function collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty) {
 	}
 	return result;
 }
+async function applyEventTypesFlag(params) {
+	try {
+		const eventTypes = parseEventTypesFlag(params.values);
+		const unknown = unknownEventTypes(eventTypes);
+		if (unknown.length > 0 && !params.quiet) process.stderr.write(unknownEventTypesWarning(unknown));
+		const baseRules = params.endpointId !== void 0 && !bodyHasRules(params.body) ? await currentEndpointRules(params.endpointId, params.listEndpoints) : {};
+		return withEventTypes(params.body, eventTypes, baseRules);
+	} catch (error) {
+		if (error instanceof EventTypesFlagError) throw new Errors.CLIError(error.message);
+		throw error;
+	}
+}
 function collectValues(parameters, flags) {
 	const values = {};
 	for (const parameter of parameters) {
@@ -5821,6 +5999,17 @@ const OPERATION_HINTS = {
 	verifyAgentSignup: "Tip: pass --verification-code <code> (or --code; both work). The response carries OAuth tokens but not your assigned inbox domain; run `primitive domains list` (or `primitive whoami`) after success to see the managed *.primitive.email address that routes to this account."
 };
 const OPERATION_FLAG_ALIASES = { verifyAgentSignup: { verification_code: ["code"] } };
+const OPERATION_EXTRA_BODY_FLAGS = { addDomain: { "mail-relay": {
+	property: "mail_relay",
+	description: "Keep your existing mailbox provider: the domain's MX points at a Primitive mail relay, which forwards mail to your mailboxes and stores a copy in Primitive. Requires mail relay to be enabled for your account. Google Workspace only for now."
+} } };
+const MAIL_RELAY_NOT_ENABLED_MESSAGE = "Mail relay is not enabled for this account, so the domain was not added. Retry without --mail-relay to point the domain's MX at Primitive directly, or ask Primitive to enable mail relay for your account.";
+const MAIL_RELAY_UNAVAILABLE_MESSAGE = "No mail relay is available on this API server right now, so the domain was not added. Retry later, or retry without --mail-relay to point the domain's MX at Primitive directly.";
+const OPERATION_ERROR_HINTS = { addDomain: (code, body) => {
+	if (code === "mail_relay_unavailable") return MAIL_RELAY_UNAVAILABLE_MESSAGE;
+	const mailRelay = body !== null && typeof body === "object" && body.mail_relay === true;
+	if (code === "feature_disabled" && mailRelay) return MAIL_RELAY_NOT_ENABLED_MESSAGE;
+} };
 const OPERATION_SUCCESS_HOOKS = { verifyAgentSignup: ({ envelope, configDir, apiBaseUrl, writeStderr }) => {
 	const data = envelope?.data;
 	if (!data?.access_token || !data?.refresh_token) return;
@@ -5876,6 +6065,16 @@ function createOperationCommand(operation) {
 						}
 					} else body = explicit;
 				}
+				if (EVENT_TYPES_FLAG_OPERATIONS.has(operation.sdkName) && Array.isArray(parsedFlags["event-types"])) body = await applyEventTypesFlag({
+					body,
+					values: parsedFlags["event-types"],
+					endpointId: operation.sdkName === "updateEndpoint" && typeof parsedFlags.id === "string" ? parsedFlags.id : void 0,
+					listEndpoints: () => listEndpoints({
+						client: apiClient.client,
+						responseStyle: "fields"
+					}),
+					quiet: parsedFlags.json === true
+				});
 				if (operation.bodyRequired && body === void 0) throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
 				const operationFn = sdk_gen_exports[operation.sdkName];
 				const query = collectValues(operation.queryParams, parsedFlags);
@@ -5899,6 +6098,8 @@ function createOperationCommand(operation) {
 				if (result.error) {
 					const errorPayload = extractErrorPayload(result.error);
 					writeErrorWithHints(errorPayload);
+					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body);
+					if (operationErrorHint) process.stderr.write(`${operationErrorHint}\n`);
 					if (replyStateSurface && isAwaitingRejectedError(errorPayload)) process.stderr.write(`${awaitingRejectedError(replyStateSurface).message}\n`);
 					if (automatedSurface && isAutomatedRejectedError(errorPayload)) process.stderr.write(`${automatedRejectedError(automatedSurface).message}\n`);
 					surfaceUnauthorizedHint({
@@ -6002,7 +6203,7 @@ function createOperationCommand(operation) {
 	return OperationCommand;
 }
 const EMPTY_RESULT_HINTS = {
-	listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints test` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an inbound `email.received` event fans out to your endpoints. If you have no endpoints, run `primitive endpoints list` to check.",
+	listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints test` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an event fans out to your endpoints: an inbound `email.received`, or a `sent_email.*` event for an endpoint that lists it in rules.event_types (they arrive within a few minutes of the result). If you have no endpoints, run `primitive endpoints list` to check.",
 	listEndpoints: "(no results) No webhook endpoints configured. Add one with `primitive endpoints create --url <your-url>`.",
 	listEmails: "(no results) No inbound emails received yet on this account. Send one to a verified domain to populate this list. For a compact view, prefer `primitive emails latest`.",
 	listDomains: "(no results) No domains on this account. Add one with `primitive domains add --domain <yourdomain.example>`.",