shalomail 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# shalom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give your AI agents a real, end-to-end encrypted email address.
+
+`shalom` is the command line for [Shalom Mail](https://shalomail.com). Each agent gets its own `@shalomail.com` mailbox. It receives, reads and sends real email, from Shalom or from anywhere, and every command speaks JSON. The mailbox's private key is created on the agent's machine and never leaves it: the server stores mail sealed and cannot read it.
+
+## Start
+
+```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
+```
+
+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
+shalom inbox --json
+shalom read 3f9c2a1b --json
+shalom reply 3f9c2a1b --text "Got it, thanks."
+shalom send --to ana@example.com --subject "Weekly report" \
+  --text-file report.md --attach report.pdf
+```
+
+Ids can be shortened to their first 8 characters. Text can also come from standard input.
+
+## React to every new email
+
+```sh
+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`.
+
+```python
+# agent.py
+import json, subprocess, sys
+msg = json.load(sys.stdin)
+answer = f"Hi {msg['from']['name'] or 'there'}, we received: {msg['subject']}"
+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_AGENT_TOKEN=shalom_agent_... shalom inbox --json
+```
+
+Store the token as a secret: it contains the mailbox's private key.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `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 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 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`) |
+| `shalom reply <id>` | Replies in the same thread (`--all`) |
+| `shalom move <id> --to <folder>` | Moves to inbox, archive, spam or trash |
+| `shalom mark <id>` | `--read`, `--unread`, `--star`, `--unstar` |
+| `shalom watch` | Waits for new mail (`--exec`, `--interval`, `--mark-read`) |
+
+Every command accepts `--json`, `--as <address>` to pick the mailbox, and `--api <url>`.
+
+## 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.
+- 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. 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`.
+
+Docs: https://shalomail.com/en/agents/

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+// 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 (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. */
+  watch(opts?: { interval?: number; signal?: AbortSignal; includeExisting?: 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 }>;
+  deleteAgent(address: string): Promise<void>;
+}