@aimail/mail 0.1.0-rc.9 → 0.1.7

package/README.md

@@ -0,0 +1,49 @@
+# @aimail/mail
+
+Platform-neutral AIMail config resolution for TypeScript: session id / email
+/ recipient → `agentmail.json` → `AgentConfig`. Pure functions — no framework
+imports, no host wiring.
+
+[![npm](https://img.shields.io/npm/v/@aimail/mail)](https://www.npmjs.com/package/@aimail/mail)
+
+## Install
+
+```bash
+pnpm add @aimail/mail
+```
+
+## What it does
+
+Every adapter needs the same three lookups, sourced from the per-address
+`agentmail.json` bindings under `$AIMAIL_HOME` (default `~/.aimail`):
+
+- `resolveBySessionId(sessionId)` — session-file match first, then agent_id
+  field match. For dsh session uuids and OpenClaw/pi agent ids.
+- `resolveByEmail(email)` — exact registered-address match. Throws when
+  unbound.
+- `resolveByRecipient(recipient)` — exact match first, then persona-strip
+  fallback (recipient local part ends with `.<registered local part>`),
+  mirroring the Python `route_agent_for_email` semantics. Inbound routing for
+  single-in-multi-out platforms (one gateway hosts many agents; mail can
+  arrive at role aliases).
+- `resolveConfig()`-style composition is left to each adapter: the identity
+  source (pointer file / factory ctx / env) is platform-specific by design.
+
+## Scope narrowing
+
+`ResolveOptions.systemId` narrows the scan to one system; when omitted the
+`AIMAIL_SYSTEM_ID` env is used; when that is also empty, all systems under
+`$AIMAIL_HOME/systems/` are scanned (two-level traversal:
+`systems/{system_id}/{address_dir}/agentmail.json`).
+
+Unbound resolutions throw loudly (`no aimail binding for …`) — callers
+surface that to the model/user instead of guessing an identity.
+
+## Related repositories
+
+- [metercai/aimail](https://github.com/metercai/aimail) — the AIMail monorepo:
+  CLI (`cli/`), Python SDK (`pysdk/`), TypeScript SDK (`tssdk/`, you are here),
+  bridge distributions.
+- [metercai/aimail-gateway](https://github.com/metercai/aimail-gateway) — the
+  AIMail gateway: SMTP/HTTP mail service and the address & activation APIs
+  that create the bindings being resolved here.

package/lib/index.d.ts

@@ -6,7 +6,7 @@ export interface MailToolCtx {
 }
 /** Resolution options shared by every resolver. */
 export interface ResolveOptions {
-    /** Explicit system scope; defaults to the AMAIL_SYSTEM_ID env (empty = scan all). */
+    /** Explicit system scope; defaults to the AIMAIL_SYSTEM_ID env (empty = scan all). */
     systemId?: string;
 }
 /**

package/lib/index.js

@@ -1,21 +1,21 @@
 /**
- * @aimail/mail — platform-neutral AgentMail config resolution.
+ * @aimail/mail — platform-neutral AIMail config resolution.
  *
  * Pure functions: sessionId / email / agentId → agentmail.json → AgentConfig.
  * No framework imports (no cordis, no dsh-sdk); each platform adapter
  * (dsh-aimail, openclaw-aimail) binds these to its own identity source.
  *
  * Identity = agentmail.json only (single source of truth); the optional
- * AMAIL_SYSTEM_ID env narrows the scan scope. Unbound resolutions throw.
+ * AIMAIL_SYSTEM_ID env narrows the scan scope. Unbound resolutions throw.
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { cleanAddr, loadConfigByAgentId, loadConfigByEmail, loadConfigBySessionId, systemDir, } from '@aimail/mail-core';
 function systemIdFrom(opts) {
-    return opts.systemId ?? process.env.AMAIL_SYSTEM_ID ?? '';
+    return opts.systemId ?? process.env.AIMAIL_SYSTEM_ID ?? '';
 }
 function unbound(what) {
-    return new Error(`no agentmail binding for ${what} — run bind_agent.py first`);
+    return new Error(`no aimail binding for ${what} — run bind_agent.py first`);
 }
 /** Scan one system dir (or all systems) for every bound AgentConfig. */
 async function scanAllConfigs(systemId) {
@@ -59,7 +59,7 @@ async function scanAllConfigs(systemId) {
  */
 export async function resolveBySessionId(sessionId, opts = {}) {
     if (!sessionId)
-        throw new Error('no session id to resolve agentmail config');
+        throw new Error('no session id to resolve aimail config');
     const systemId = systemIdFrom(opts);
     let cfg = await loadConfigBySessionId(systemId, sessionId);
     if (!cfg && systemId)

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@aimail/mail",
-  "description": "AgentMail platform-neutral config resolution: sessionId/email/recipient → agentmail.json → AgentConfig (pure functions, no framework deps).",
-  "version": "0.1.0-rc.9",
+  "description": "AIMail platform-neutral config resolution: sessionId/email/recipient → agentmail.json → AgentConfig (pure functions, no framework deps).",
+  "version": "0.1.7",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metercai/aimail-sdk-ts.git",
-    "directory": "packages/mail"
+    "url": "https://github.com/metercai/aimail"
   },
   "type": "module",
   "main": "lib/index.js",
@@ -27,7 +27,14 @@
   "license": "MIT",
   "peerDependencies": {},
   "dependencies": {
-    "@aimail/mail-core": "^0.1.0-rc.9"
+    "@aimail/mail-core": "^0.1.7"
   },
-  "devDependencies": {}
-}
+  "devDependencies": {},
+  "keywords": [
+    "aimail",
+    "agent-mail",
+    "config",
+    "resolution",
+    "binding"
+  ]
+}