@primitivedotdev/sdk 0.18.0 → 0.19.0

package/dist/oclif/commands/send.js

@@ -1,7 +1,8 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { listDomains, sendEmail } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorCode, extractErrorPayload, formatErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { API_ERROR_CODES, extractErrorCode, extractErrorPayload, formatErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
 // `primitive send` is the agent-grade shortcut for the most common
 // case: send a fresh outbound email. It wraps `sending:send-email`
 // with two ergonomic defaults that the underlying operation can't
@@ -53,7 +54,7 @@ function deriveSubject(body) {
 function isVerifiedDomain(domain) {
     return domain.is_active === true;
 }
-async function pickDefaultFromAddress(apiClient) {
+async function pickDefaultFromAddress(apiClient, authFailureContext) {
     const result = await listDomains({
         client: apiClient.client,
         responseStyle: "fields",
@@ -65,8 +66,12 @@ async function pickDefaultFromAddress(apiClient) {
         // Surface the auth hint via writeErrorWithHints and bail with
         // a focused message instead of the verbose "underlying error"
         // wrapping.
-        if (extractErrorCode(errorPayload) === "unauthorized") {
+        if (extractErrorCode(errorPayload) === API_ERROR_CODES.unauthorized) {
             writeErrorWithHints(errorPayload);
+            removeStaleSavedCredentialOnUnauthorized({
+                ...authFailureContext,
+                payload: errorPayload,
+            });
             // exit: 1 to match the run() unauthorized path (which uses
             // `process.exitCode = 1`). oclif's CLIError defaults to 2,
             // so without this override the same "unauthorized" condition
@@ -107,7 +112,7 @@ class SendCommand extends Command {
     ];
     static flags = {
         "api-key": Flags.string({
-            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
         "base-url": Flags.string({
@@ -149,11 +154,23 @@ class SendCommand extends Command {
             throw new Errors.CLIError("Either --body or --html (or both) is required.");
         }
         await runWithTiming(flags.time, async () => {
-            const apiClient = new PrimitiveApiClient({
+            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const auth = resolveCliAuth({
                 apiKey: flags["api-key"],
                 baseUrl: flags["base-url"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                baseUrl: auth.baseUrl,
             });
-            const from = flags.from ?? (await pickDefaultFromAddress(apiClient));
+            const authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            const from = flags.from ??
+                (await pickDefaultFromAddress(apiClient, authFailureContext));
             const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
             const result = await sendEmail({
                 body: {
@@ -174,7 +191,12 @@ class SendCommand extends Command {
                 responseStyle: "fields",
             });
             if (result.error) {
-                writeErrorWithHints(extractErrorPayload(result.error));
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    ...authFailureContext,
+                    payload: errorPayload,
+                });
                 process.exitCode = 1;
                 return;
             }

package/dist/oclif/commands/whoami.js

@@ -1,7 +1,8 @@
 import { Command, Errors, Flags } from "@oclif/core";
 import { getAccount } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
 // `primitive whoami` is the credentials smoke-test the AGX
 // walkthrough kept asking for. Before this command, a user with a
 // suspect API key had no fast way to verify "is my key live and
@@ -21,7 +22,7 @@ class WhoamiCommand extends Command {
     ];
     static flags = {
         "api-key": Flags.string({
-            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
         "base-url": Flags.string({
@@ -35,16 +36,29 @@ class WhoamiCommand extends Command {
     async run() {
         const { flags } = await this.parse(WhoamiCommand);
         await runWithTiming(flags.time, async () => {
-            const apiClient = new PrimitiveApiClient({
+            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const auth = resolveCliAuth({
                 apiKey: flags["api-key"],
                 baseUrl: flags["base-url"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                baseUrl: auth.baseUrl,
             });
             const result = await getAccount({
                 client: apiClient.client,
                 responseStyle: "fields",
             });
             if (result.error) {
-                writeErrorWithHints(extractErrorPayload(result.error));
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload: errorPayload,
+                });
                 process.exitCode = 1;
                 return;
             }

package/dist/oclif/fish-completion.js

@@ -73,7 +73,7 @@ export function renderFishCompletion(binName) {
             ]) {
                 lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l '${fishEscape(parameter.name.replace(/_/g, "-"))}' -r -d '${fishEscape(parameter.description ?? parameter.name)}'`);
             }
-            lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'api-key' -r -d 'Primitive API key (defaults to PRIMITIVE_API_KEY)'`, `complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'base-url' -r -d 'API base URL (defaults to PRIMITIVE_API_URL or production)'`);
+            lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'api-key' -r -d 'Primitive API key (defaults to PRIMITIVE_API_KEY or saved primitive login credentials)'`, `complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'base-url' -r -d 'API base URL (defaults to PRIMITIVE_API_URL or production)'`);
             if (operation.hasJsonBody) {
                 lines.push(`complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'body' -r -d 'JSON request body'`, `complete -c ${binName} -n '${operationCondition(operation).replace(BIN_PLACEHOLDER, binName)}' -l 'body-file' -r -d 'Path to a JSON file used as the request body'`);
             }

package/dist/oclif/index.js

@@ -2,6 +2,8 @@ import { Args, Command, Errors } from "@oclif/core";
 import { operationManifest, } from "../openapi/index.js";
 import { createOperationCommand } from "./api-command.js";
 import EmailsLatestCommand from "./commands/emails-latest.js";
+import LoginCommand from "./commands/login.js";
+import LogoutCommand from "./commands/logout.js";
 import SendCommand from "./commands/send.js";
 import WhoamiCommand from "./commands/whoami.js";
 import { renderFishCompletion } from "./fish-completion.js";
@@ -116,6 +118,10 @@ export const COMMANDS = {
     // operation stays available under sending:send-email for callers
     // who want every flag.
     send: SendCommand,
+    // `login` creates and stores an org-scoped CLI API key via browser approval.
+    login: LoginCommand,
+    // `logout` revokes the saved CLI API key and removes local credentials.
+    logout: LogoutCommand,
     // `whoami` is the credentials smoke test. Prints the account the
     // current API key authenticates as. AGX walkthroughs kept
     // wanting this before risking a real call against a possibly-

package/dist/openapi/openapi.generated.js

@@ -31,6 +31,10 @@ export const openapiDocument = {
         }
     ],
     "tags": [
+        {
+            "name": "CLI",
+            "description": "Browser-assisted CLI authentication"
+        },
         {
             "name": "Account",
             "description": "Manage your account settings, storage, and webhook secret"
@@ -61,6 +65,251 @@ export const openapiDocument = {
         }
     ],
     "paths": {
+        "/cli/login/start": {
+            "post": {
+                "operationId": "startCliLogin",
+                "summary": "Start CLI browser login",
+                "description": "Starts a browser-assisted CLI login session. The response includes a\ndevice code for polling and a user code that the user approves in the\nbrowser. This endpoint does not require an API key.\n",
+                "tags": [
+                    "CLI"
+                ],
+                "security": [],
+                "requestBody": {
+                    "required": false,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/StartCliLoginInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "CLI login session created",
+                        "headers": {
+                            "Cache-Control": {
+                                "schema": {
+                                    "type": "string"
+                                },
+                                "description": "Always `no-store`"
+                            }
+                        },
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/CliLoginStartResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "429": {
+                        "$ref": "#/components/responses/RateLimited"
+                    }
+                }
+            }
+        },
+        "/cli/login/poll": {
+            "post": {
+                "operationId": "pollCliLogin",
+                "summary": "Poll CLI browser login",
+                "description": "Polls a CLI login session until the browser approval either succeeds,\nis denied, expires, or is polled too quickly. The API key is generated\nonly after approval and is returned exactly once.\n",
+                "tags": [
+                    "CLI"
+                ],
+                "security": [],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/PollCliLoginInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "CLI login approved and API key created",
+                        "headers": {
+                            "Cache-Control": {
+                                "schema": {
+                                    "type": "string"
+                                },
+                                "description": "Always `no-store`"
+                            }
+                        },
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/CliLoginPollResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Invalid request, pending authorization, slow polling, expired token, or invalid device code",
+                        "headers": {
+                            "Retry-After": {
+                                "schema": {
+                                    "type": "integer"
+                                },
+                                "description": "Seconds to wait before polling again when the error code is `slow_down`"
+                            }
+                        },
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                },
+                                "examples": {
+                                    "authorization_pending": {
+                                        "summary": "Awaiting browser approval",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "authorization_pending",
+                                                "message": "CLI login is still pending browser approval"
+                                            }
+                                        }
+                                    },
+                                    "expired_token": {
+                                        "summary": "Login session expired",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "expired_token",
+                                                "message": "CLI login code expired; run primitive login again"
+                                            }
+                                        }
+                                    },
+                                    "invalid_device_code": {
+                                        "summary": "Unknown device code",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "invalid_device_code",
+                                                "message": "Invalid CLI login device code"
+                                            }
+                                        }
+                                    },
+                                    "slow_down": {
+                                        "summary": "Polling too quickly",
+                                        "value": {
+                                            "success": false,
+                                            "error": {
+                                                "code": "slow_down",
+                                                "message": "Polling too quickly; slow down and retry later"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "CLI login was denied in the browser",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ErrorResponse"
+                                },
+                                "example": {
+                                    "success": false,
+                                    "error": {
+                                        "code": "access_denied",
+                                        "message": "CLI login was denied in the browser"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/cli/logout": {
+            "post": {
+                "operationId": "cliLogout",
+                "summary": "Revoke the current CLI API key",
+                "description": "Revokes the API key used to authenticate the request. CLI clients use\nthis endpoint during `primitive logout` before removing local credentials.\n",
+                "tags": [
+                    "CLI"
+                ],
+                "requestBody": {
+                    "required": false,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/CliLogoutInput"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "CLI API key revoked",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "allOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SuccessEnvelope"
+                                        },
+                                        {
+                                            "type": "object",
+                                            "properties": {
+                                                "data": {
+                                                    "$ref": "#/components/schemas/CliLogoutResult"
+                                                }
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "$ref": "#/components/responses/ValidationError"
+                    },
+                    "401": {
+                        "$ref": "#/components/responses/Unauthorized"
+                    },
+                    "403": {
+                        "$ref": "#/components/responses/Forbidden"
+                    },
+                    "404": {
+                        "$ref": "#/components/responses/NotFound"
+                    }
+                }
+            }
+        },
         "/account": {
             "get": {
                 "operationId": "getAccount",
@@ -987,7 +1236,7 @@ export const openapiDocument = {
             "post": {
                 "operationId": "discardEmailContent",
                 "summary": "Discard email content",
-                "description": "Permanently deletes the email's raw bytes, parsed body (text + HTML),\nand attachments while preserving metadata (sender, recipient,\nsubject, timestamps, hashes, attachment manifest) for audit logs.\nIdempotent: a second call returns success with\n`already_discarded: true` and does no work.\n\n**Gated** on the customer's discard-content opt-in (managed in the\ndashboard at Settings > Webhooks). When the toggle is off, this\nendpoint returns `403` with code `discard_not_enabled` and a\nmessage pointing the human at the dashboard. There is intentionally\nno API to flip this toggle — opting in to a destructive,\nnon-reversible operation must be a deliberate human click in the\nUI.\n",
+                "description": "Permanently deletes the email's raw bytes, parsed body (text + HTML),\nand attachments while preserving metadata (sender, recipient,\nsubject, timestamps, hashes, attachment manifest) for audit logs.\nIdempotent: a second call returns success with\n`already_discarded: true` and does no work.\n\n**Gated** on the customer's discard-content opt-in (managed in the\ndashboard at Settings > Webhooks). When the toggle is off, this\nendpoint returns `403` with code `discard_not_enabled` and a\nmessage pointing the human at the dashboard. There is intentionally\nno API to flip this toggle. Opting in to a destructive,\nnon-reversible operation must be a deliberate human click in the\nUI.\n",
                 "tags": [
                     "Emails"
                 ],
@@ -2157,7 +2406,12 @@ export const openapiDocument = {
                                     "outbound_response_malformed",
                                     "outbound_relay_failed",
                                     "discard_not_enabled",
-                                    "inbound_not_repliable"
+                                    "inbound_not_repliable",
+                                    "authorization_pending",
+                                    "slow_down",
+                                    "access_denied",
+                                    "expired_token",
+                                    "invalid_device_code"
                                 ]
                             },
                             "message": {
@@ -2295,6 +2549,135 @@ export const openapiDocument = {
                     "subject"
                 ]
             },
+            "StartCliLoginInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "device_name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 80,
+                        "description": "Human-readable device name shown during browser approval"
+                    },
+                    "metadata": {
+                        "type": "object",
+                        "additionalProperties": true,
+                        "description": "Optional client metadata stored with the login session; serialized JSON must be 2048 bytes or fewer"
+                    }
+                }
+            },
+            "CliLoginStartResult": {
+                "type": "object",
+                "properties": {
+                    "device_code": {
+                        "type": "string",
+                        "description": "Opaque code used by the CLI to poll for approval"
+                    },
+                    "user_code": {
+                        "type": "string",
+                        "pattern": "^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$",
+                        "description": "Short code the user confirms in the browser"
+                    },
+                    "verification_uri": {
+                        "type": "string",
+                        "description": "Browser URL where the user approves the login"
+                    },
+                    "verification_uri_complete": {
+                        "type": "string",
+                        "description": "Browser URL with the user code prefilled"
+                    },
+                    "expires_in": {
+                        "type": "integer",
+                        "description": "Seconds until the login session expires"
+                    },
+                    "interval": {
+                        "type": "integer",
+                        "description": "Minimum seconds between poll requests"
+                    }
+                },
+                "required": [
+                    "device_code",
+                    "user_code",
+                    "verification_uri",
+                    "verification_uri_complete",
+                    "expires_in",
+                    "interval"
+                ]
+            },
+            "PollCliLoginInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "device_code": {
+                        "type": "string",
+                        "minLength": 1
+                    }
+                },
+                "required": [
+                    "device_code"
+                ]
+            },
+            "CliLoginPollResult": {
+                "type": "object",
+                "properties": {
+                    "api_key": {
+                        "type": "string",
+                        "description": "Newly-created API key for CLI authentication"
+                    },
+                    "key_id": {
+                        "type": "string",
+                        "format": "uuid"
+                    },
+                    "key_prefix": {
+                        "type": "string"
+                    },
+                    "org_id": {
+                        "type": "string",
+                        "format": "uuid"
+                    },
+                    "org_name": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    }
+                },
+                "required": [
+                    "api_key",
+                    "key_id",
+                    "key_prefix",
+                    "org_id",
+                    "org_name"
+                ]
+            },
+            "CliLogoutInput": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "key_id": {
+                        "type": "string",
+                        "format": "uuid",
+                        "description": "Optional key id guard; when provided it must match the authenticated API key"
+                    }
+                }
+            },
+            "CliLogoutResult": {
+                "type": "object",
+                "properties": {
+                    "revoked": {
+                        "type": "boolean",
+                        "const": true
+                    },
+                    "key_id": {
+                        "type": "string",
+                        "format": "uuid"
+                    }
+                },
+                "required": [
+                    "revoked",
+                    "key_id"
+                ]
+            },
             "Account": {
                 "type": "object",
                 "properties": {