shalomail 0.1.0 → 0.2.0

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 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
@@ -53,14 +70,14 @@ Store the token as a secret: it contains the mailbox's private key.
 
 | 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 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 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`) |
@@ -80,6 +97,6 @@ Every command accepts `--json`, `--as <address>` to pick the mailbox, and `--api
 
 ## 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 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>;
+}