shalomail 0.1.0 → 0.2.1

package/README.md

@@ -8,10 +8,27 @@ Give your AI agents a real, end-to-end encrypted email address.
 
 ```sh
 npm install -g shalomail       # Node.js 20 or newer
-shalom login                   # paste an API key from Settings > API keys
-shalom agents create support   # creates support@shalomail.com
+shalom login                   # opens shalomail.com to connect this terminal
+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`.
+
+On a machine without a browser (SSH, server), `shalom login --no-browser` prints the link and the code: open it on any device where you are signed in to Shalom and confirm. For CI, `shalom login --key shalom_sk_...` uses an API key created on the AI agents page.
+
+## Use it from code
+
+```js
+import { Agent } from 'shalomail';
+
+const agent = Agent.fromToken(process.env.SHALOM_AGENT_TOKEN);
+for await (const msg of agent.watch()) {
+  await agent.reply(msg.id, { text: `Got it: ${msg.subject}` });
+}
+```
+
+Full SDK and HTTP API reference: https://shalomail.com/developers/
+
 ## Read, reply and send
 
 ```sh
@@ -30,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
@@ -43,24 +60,24 @@ 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
 
 | Command | What it does |
 | --- | --- |
-| `shalom login` | Saves your account API key on this machine |
+| `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>` | 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`) |
@@ -74,12 +91,13 @@ 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`.
 
 ## 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. Subscribe in Settings 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

@@ -0,0 +1,83 @@
+// Types for the shalomail Node SDK: import { Agent, Account } from 'shalomail'.
+
+export type Folder = 'inbox' | 'starred' | 'sent' | 'drafts' | 'archive' | 'spam' | 'trash';
+export type Person = { name: string; address: string };
+
+export type Summary = {
+  id: string;
+  folder: string;
+  from: Person | null;
+  to: Person[];
+  subject: string;
+  date: string;
+  receivedAt: number;
+  snippet: string;
+  attachments: number;
+  unread: boolean;
+  starred: boolean;
+  /** Shalom to Shalom: sender verified by the server certificate and sealed end to end. */
+  verifiedSender: boolean;
+  /** Mail from other providers: DMARC result seen on arrival. */
+  auth: 'pass' | 'fail' | 'unknown';
+};
+
+export type Message = Omit<Summary, 'attachments'> & {
+  messageId: string | null;
+  inReplyTo: string | null;
+  references: string | null;
+  replyTo: Person[];
+  cc: Person[];
+  text: string;
+  html: string | null;
+  attachments: { filename: string; mimeType: string; size: number; content: Uint8Array }[];
+};
+
+export type Attachment = { filename: string; content: Uint8Array; type?: string };
+
+export type SendInput = {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  text: string;
+  html?: string;
+  attachments?: Attachment[];
+  inReplyTo?: string;
+  references?: string;
+};
+
+export type SendResult = { id: string; external: number; internal: number };
+
+export declare class ApiError extends Error {
+  status: number;
+  code: string;
+}
+
+/** One agent mailbox. Opening, sealing and sending happen on your machine. */
+export declare class Agent {
+  /** 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;
+  readonly address: string;
+  inbox(opts?: { folder?: Folder; limit?: number; unread?: boolean }): Promise<Summary[]>;
+  /** Marks the message as read unless markRead is false. Ids can be shortened to 8 characters. */
+  read(id: string, opts?: { markRead?: boolean }): Promise<Message>;
+  send(msg: SendInput, opts?: { trustNewKey?: boolean }): Promise<SendResult>;
+  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. 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. */
+export declare class Account {
+  constructor(apiKey?: string, opts?: { api?: string });
+  /** plan.limit is null on the Unlimited plan. */
+  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 }>;
+  /** 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>;
+}