shalomail 0.2.0 → 0.2.2

package/README.md

@@ -9,7 +9,7 @@ Give your AI agents a real, end-to-end encrypted email address.
 ```sh
 npm install -g shalomail       # Node.js 20 or newer
 shalom login                   # opens shalomail.com to connect this terminal
-shalom agents create support   # creates support@shalomail.com
+shalom agents create yourname-bot   # creates yourname-bot@shalomail.com
 ```
 
 No global install? `npx shalomail <command>` works anywhere, for example `npx shalomail login`. The command answers to both `shalom` and `shalomail`.
@@ -47,7 +47,7 @@ Ids can be shortened to their first 8 characters. Text can also come from standa
 shalom watch --exec "python agent.py" --mark-read
 ```
 
-`watch` waits for new mail and runs your program once per message, with the message as JSON on standard input: `id`, `from`, `to`, `cc`, `subject`, `date`, `text`, `html`, `messageId`, `verifiedSender` and `attachments`. The environment also gets `SHALOM_MESSAGE_ID`, `SHALOM_FROM` and `SHALOM_SUBJECT`.
+`watch` waits for new mail and runs your program once per message, with the message as JSON on standard input: `id`, `from`, `to`, `cc`, `subject`, `date`, `text`, `html`, `messageId`, `verifiedSender` and `attachments`. The environment also gets `SHALOM_MESSAGE_ID`, `SHALOM_FROM` and `SHALOM_SUBJECT`. With `--mark-read`, a message is marked read only after your program exits with 0, and messages still unread when `watch` restarts are handed to it again. In the SDK, `agent.watch({ includeUnread: true })` does the same.
 
 ```python
 # agent.py
@@ -60,11 +60,11 @@ subprocess.run(["shalom", "reply", msg["id"], "--text", answer], check=True)
 ## Run it on a server
 
 ```sh
-shalom agents export support@shalomail.com   # prints SHALOM_AGENT_TOKEN
+shalom agents export yourname-bot@shalomail.com   # prints SHALOM_AGENT_TOKEN
 SHALOM_AGENT_TOKEN=shalom_agent_... shalom inbox --json
 ```
 
-Store the token as a secret: it contains the mailbox's private key.
+Store the token as a secret: it contains the mailbox's private key. On servers, prefer mounting it as a file and pointing `SHALOM_AGENT_TOKEN_FILE` to it; programs started by `watch --exec` never receive it.
 
 ## Commands
 
@@ -73,11 +73,11 @@ Store the token as a secret: it contains the mailbox's private key.
 | `shalom login` | Connects this terminal to your account in the browser (`--no-browser`, `--key`) |
 | `shalom agents list` | Lists your agent mailboxes and your plan |
 | `shalom agents create <name>` | Creates `<name>@shalomail.com`, with the private key on this machine |
-| `shalom agents delete <address>` | Deletes the mailbox and all its mail; the address stays reserved for you |
-| `shalom agents rotate <address>` | Issues a new API key for the mailbox |
+| `shalom agents delete <address>` | Deletes the mailbox and all its mail (needs the mailbox saved on this machine); the address stays reserved for you |
+| `shalom agents rotate <address>` | Issues a new API key for the mailbox, sealed to its private key |
 | `shalom agents export <address>` | Prints `SHALOM_AGENT_TOKEN` |
-| `shalom agents import <token>` | Saves an exported mailbox on this machine |
-| `shalom plan` / `shalom upgrade <5\|12\|unlimited>` | Shows your plan, or opens checkout |
+| `shalom agents import <token>` | Saves an exported mailbox on this machine (`--yes` to replace one with other keys) |
+| `shalom plan` / `shalom upgrade` | Shows your plan, or opens the plans page in the app |
 | `shalom inbox` | Lists messages (`--folder`, `--limit`, `--unread`) |
 | `shalom read <id>` | Opens a message (`--save-attachments <dir>`) |
 | `shalom send` | Sends a message (`--to`, `--cc`, `--bcc`, `--subject`, `--text`, `--text-file`, `--html-file`, `--attach`) |
@@ -91,12 +91,14 @@ Every command accepts `--json`, `--as <address>` to pick the mailbox, and `--api
 ## Security
 
 - Each mailbox's private key stays in `~/.config/shalom` (folder 700, files 600) or in your `SHALOM_AGENT_TOKEN`.
-- Your account key only creates and deletes agent mailboxes. Each mailbox's key only reads and sends through it.
+- Your account key creates agent mailboxes and shows your plan. It cannot read or send for a mailbox, cannot delete one without that mailbox's own key, and cannot touch billing: plans are changed in the app.
+- The keys of shalomail.com are built into the package, so a swapped server or an intercepted connection cannot fake a verified sender.
 - Between Shalom addresses, mail is sealed end to end and the sender is verified. To other providers it goes as regular email.
-- The encryption keys of Shalom contacts are pinned on first use; if one changes, sending stops until you confirm with `--trust-new-key`.
+- The encryption keys of Shalom contacts are pinned on first use, when you send to them or receive from them. If one changes, mail from that contact is no longer marked as verified (`verifiedSender: false`, `keyChanged: true`) and sending stops until you confirm with `--trust-new-key`.
+- Text from emails (sender, subject, body, attachment names) is printed without terminal control characters, so a message cannot change your terminal.
 
 ## Plans
 
-Free: 2 agent mailboxes. Agents 5: up to 5 for US$ 4.99 a month. Agents 12: up to 12 for US$ 9.99 a month. Unlimited: no mailbox limit, up to 250 new mailboxes a day, for US$ 49.90 a month. Subscribe on the AI agents page of the app or with `shalom upgrade`.
+Free: 2 agent mailboxes. Agents 5: up to 5 for US$ 4.99 a month. Agents 12: up to 12 for US$ 9.99 a month. Unlimited: no mailbox limit, up to 250 new mailboxes a day, for US$ 49.90 a month. Subscribe on the AI agents page of the app (`shalom upgrade` opens it).
 
 Docs: https://shalomail.com/en/agents/

package/dist/index.d.ts

@@ -55,7 +55,7 @@ export declare class ApiError extends Error {
 
 /** One agent mailbox. Opening, sealing and sending happen on your machine. */
 export declare class Agent {
-  /** From SHALOM_AGENT_TOKEN (see `shalom agents export`). */
+  /** From SHALOM_AGENT_TOKEN or the file in SHALOM_AGENT_TOKEN_FILE (see `shalom agents export`). */
   static fromToken(token?: string, opts?: { api?: string }): Agent;
   /** From the file the CLI saved in ~/.config/shalom/agents. */
   static fromFile(address: string, opts?: { api?: string }): Agent;
@@ -67,8 +67,8 @@ export declare class Agent {
   reply(id: string, msg: { text: string; html?: string; all?: boolean; quote?: boolean; attachments?: Attachment[] }, opts?: { trustNewKey?: boolean }): Promise<SendResult>;
   move(ids: string | string[], folder: 'inbox' | 'archive' | 'spam' | 'trash'): Promise<void>;
   mark(ids: string | string[], change: { read?: boolean; starred?: boolean }): Promise<void>;
-  /** New inbox messages, one at a time, until the loop breaks or the signal aborts. */
-  watch(opts?: { interval?: number; signal?: AbortSignal; includeExisting?: boolean }): AsyncGenerator<Message>;
+  /** New inbox messages, one at a time, until the loop breaks or the signal aborts. includeUnread also yields the unread ones already there, to resume after a restart. */
+  watch(opts?: { interval?: number; signal?: AbortSignal; includeExisting?: boolean; includeUnread?: boolean }): AsyncGenerator<Message>;
 }
 
 /** Your account: creates and deletes agent mailboxes with the account API key. */
@@ -78,5 +78,6 @@ export declare class Account {
   listAgents(): Promise<{ agents: { id: string; address: string; name: string; createdAt: number; paused: boolean }[]; plan: { plan: string; limit: number | null; used: number } }>;
   /** The mailbox private key is created here. The returned token is the full credential: store it as a secret. */
   createAgent(name: string, opts?: { displayName?: string; save?: boolean }): Promise<{ id: string; address: string; name: string; token: string }>;
-  deleteAgent(address: string): Promise<void>;
+  /** Needs the mailbox's own credential: { token }, or the file the CLI saved. Or delete it in the app. */
+  deleteAgent(address: string, opts?: { token?: string }): Promise<void>;
 }