@push.rocks/smartjmap 1.0.0

package/dist_ts/index.d.ts

@@ -0,0 +1,2 @@
+export * from './classes.jmapclient.js';
+export * from './classes.jmapserver.js';

package/dist_ts/index.js

@@ -0,0 +1,3 @@
+export * from './classes.jmapclient.js';
+export * from './classes.jmapserver.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMseUJBQXlCLENBQUMifQ==

package/dist_ts/smartjmap.plugins.d.ts

@@ -0,0 +1,4 @@
+import * as events from 'node:events';
+import * as http from 'node:http';
+import * as net from 'node:net';
+export { events, http, net, };

package/dist_ts/smartjmap.plugins.js

@@ -0,0 +1,6 @@
+// node native
+import * as events from 'node:events';
+import * as http from 'node:http';
+import * as net from 'node:net';
+export { events, http, net, };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRqbWFwLnBsdWdpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9zbWFydGptYXAucGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjO0FBQ2QsT0FBTyxLQUFLLE1BQU0sTUFBTSxhQUFhLENBQUM7QUFDdEMsT0FBTyxLQUFLLElBQUksTUFBTSxXQUFXLENBQUM7QUFDbEMsT0FBTyxLQUFLLEdBQUcsTUFBTSxVQUFVLENBQUM7QUFFaEMsT0FBTyxFQUNMLE1BQU0sRUFDTixJQUFJLEVBQ0osR0FBRyxHQUNKLENBQUEifQ==

package/license

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Task Venture Capital GmbH <hello@task.vc>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/npmextra.json

@@ -0,0 +1,39 @@
+{
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
+      "gitrepo": "smartjmap",
+      "shortDescription": "JMAP client for mail (RFC 8620/8621)",
+      "description": "A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.",
+      "npmPackagename": "@push.rocks/smartjmap",
+      "license": "MIT",
+      "projectDomain": "push.rocks",
+      "keywords": [
+        "jmap",
+        "email",
+        "mail",
+        "rfc8620",
+        "rfc8621",
+        "fastmail",
+        "stalwart",
+        "json",
+        "http",
+        "client",
+        "typescript",
+        "event-driven",
+        "push",
+        "eventsource",
+        "message processing"
+      ]
+    }
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": [],
+    "npmRegistryUrl": "registry.npmjs.org"
+  },
+  "@git.zone/tsdoc": {
+    "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@push.rocks/smartjmap",
+  "version": "1.0.0",
+  "private": false,
+  "description": "A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
+  "main": "dist_ts/index.js",
+  "typings": "dist_ts/index.d.ts",
+  "type": "module",
+  "author": "Task Venture Capital GmbH <hello@task.vc>",
+  "license": "MIT",
+  "devDependencies": {
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsrun": "^2.0.3",
+    "@git.zone/tstest": "^3.6.3",
+    "@types/node": "^25.6.0"
+  },
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://code.foss.global/push.rocks/smartjmap.git"
+  },
+  "bugs": {
+    "url": "https://code.foss.global/push.rocks/smartjmap/issues"
+  },
+  "homepage": "https://code.foss.global/push.rocks/smartjmap#readme",
+  "browserslist": [
+    "last 1 chrome versions"
+  ],
+  "files": [
+    "ts/**/*",
+    "ts_web/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    "dist_ts_web/**/*",
+    "assets/**/*",
+    "cli.js",
+    ".smartconfig.json",
+    "license",
+    "npmextra.json",
+    "readme.md"
+  ],
+  "keywords": [
+    "jmap",
+    "email",
+    "mail",
+    "rfc8620",
+    "rfc8621",
+    "fastmail",
+    "stalwart",
+    "json",
+    "http",
+    "client",
+    "typescript",
+    "event-driven",
+    "push",
+    "eventsource",
+    "message processing"
+  ],
+  "scripts": {
+    "test": "tstest test/",
+    "build": "tsbuild --web",
+    "buildDocs": "tsdoc"
+  }
+}

package/readme.hints.md

@@ -0,0 +1,34 @@
+# Project Readme Hints
+
+Design notes for @push.rocks/smartjmap.
+
+## HTTP layer
+
+- Zero runtime dependencies: global `fetch` (Node.js 18+ floor; developed against @types/node 25). smartrequest would add no value for plain JSON-over-HTTP.
+- SSE is parsed by hand over a fetch body stream (~50 lines in `runEventStream`). The global `EventSource` was rejected deliberately: it is only default-enabled from Node 22.3 and, more importantly, the WHATWG EventSource API cannot send the `Authorization` header JMAP requires.
+
+## Watching semantics
+
+- `connect()`: session GET → capability/account validation → mailbox resolution (role match on the lowercased mailbox name, e.g. 'INBOX' → role 'inbox', falling back to case-insensitive name match) → Email state snapshot → 'connected' → initial sweep (Email/query + Email/get, emitted oldest-first) → event stream.
+- The Email state is snapshotted *before* the initial sweep and `fetchDeltas()` runs once right after the SSE stream is established, so mail arriving between connect and stream establishment is not lost; `seenEmailIds` deduplicates the overlap.
+- Event stream errors/end → silent fallback to `Email/changes` polling on `pollIntervalMs`. `cannotCalculateChanges` → full re-query resync.
+- `connect()` emits 'error' instead of throwing (mirrors smartimap). Unlike smartimap, the same instance may call `connect()` again — JMAP is stateless HTTP.
+- `disconnect()` aborts the SSE fetch and clears the poll timer; the connect-failure path also tears both down, so no handles leak either way.
+
+## RFC subset covered (1.0.0)
+
+- RFC 8620: session resource, method calls/responses, `error` method responses, RFC 7807 problem details, `#creationId` back-references (client-side use; server resolves them in EmailSubmission/set), download URL template expansion, event source (SSE StateChange).
+- RFC 8621: Mailbox/get(+query on server), Email/query, Email/get with `fetchAllBodyValues`, Email/changes, Email/set (create/update with keyword patches/destroy), Identity/get, EmailSubmission/set.
+
+## Known gaps
+
+- No upload endpoint / Blob upload (`uploadUrl` is advertised by the test server but not implemented), so `sendEmail` supports text/html bodies but not attachments.
+- No Thread/*, SearchSnippet/*, VacationResponse/*, Mailbox/set, Mailbox/changes, EmailSubmission onSuccessUpdateEmail, or result references (`resultOf`) — the client issues explicit-id calls instead.
+- `Email/get` on the test server ignores the `properties` projection and always returns the full superset; `Email/query` supports only `inMailbox`/`subject`/`text` filters and `receivedAt` sorting.
+- The client requests event-source pushes with `types=*` and reacts to Email state changes only; Mailbox counters are not tracked incrementally.
+- Initial-sweep race: an email created between the Email/query and Email/get of the sweep is picked up by the following delta fetch, not the sweep itself (dedupe prevents double emission).
+
+## By-design unbounded state (accepted)
+
+- Client: `seenEmailIds` retains every emitted email id for the instance lifetime — required for dedupe across reconnects and sweep/delta overlap; on a very long-lived, high-volume connection this grows without a pruning hook. Recreate the client to reset it.
+- Test server (in-memory helper, not production code): the per-account change log grows one entry per mutation (needed by `Email/changes`), destroyed emails leave their blobs in the blob store, and request bodies are buffered without enforcing the advertised `maxSizeRequest`.

package/readme.md

@@ -0,0 +1,287 @@
+# @push.rocks/smartjmap
+
+A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.
+
+## Install
+
+To install `@push.rocks/smartjmap`, use pnpm (or npm):
+
+```sh
+pnpm install @push.rocks/smartjmap
+```
+
+The package has zero runtime dependencies — it uses the global `fetch` available in Node.js 18+.
+
+## Usage
+
+`@push.rocks/smartjmap` connects to any JMAP server (Fastmail, Stalwart, Cyrus, ...), watches a mailbox for new mail in an event-driven way, and exposes the common mail operations: querying, reading, flagging, sending, and blob downloads.
+
+### Importing the Required Modules
+
+```typescript
+import { JmapClient, type IJmapClientConfig } from '@push.rocks/smartjmap';
+```
+
+### Configuration Object
+
+Point the client at the JMAP session resource — most servers expose it at the autodiscovery path `https://host/.well-known/jmap`. All URLs inside the session (API endpoint, download URL, event source) are resolved relative to this URL automatically.
+
+```typescript
+const jmapConfig: IJmapClientConfig = {
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  auth: {
+    accessToken: 'my-api-token',
+  },
+  mailbox: 'INBOX', // default: resolved via Mailbox role 'inbox', falling back to a name match
+  pollIntervalMs: 30000, // fallback polling cadence when the event stream is unavailable
+};
+```
+
+### Authentication: Bearer and Basic
+
+The `auth` option accepts exactly one of two shapes:
+
+```typescript
+import { JmapClient } from '@push.rocks/smartjmap';
+
+// Bearer token (OAuth2 access token or server API token)
+const bearerClient = new JmapClient({
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  auth: {
+    accessToken: 'my-api-token',
+  },
+});
+
+// Basic auth (username + password)
+const basicClient = new JmapClient({
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  auth: {
+    user: 'user@example.com',
+    pass: 'password123',
+  },
+});
+```
+
+Passing both shapes at once (or neither) throws at construction time.
+
+### Connecting and Handling Events
+
+`connect()` fetches and validates the JMAP session (the `urn:ietf:params:jmap:core` and `urn:ietf:params:jmap:mail` capabilities are required), resolves the target mailbox, and emits `connected`. It then emits a `message` event for every email currently in the mailbox and keeps watching for new mail: it prefers the JMAP event source (Server-Sent Events, RFC 8620 §7.3) and falls back to polling `Email/changes` on `pollIntervalMs` when the event stream is unavailable.
+
+```typescript
+import { JmapClient, type ISmartJmapMessage } from '@push.rocks/smartjmap';
+
+const jmapClient = new JmapClient({
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  auth: { accessToken: 'my-api-token' },
+});
+
+jmapClient.on('connected', () => {
+  console.log('Connected to the JMAP server');
+});
+
+jmapClient.on('message', (message: ISmartJmapMessage) => {
+  console.log('From:', message.from[0]?.email);
+  console.log('Subject:', message.subject);
+  console.log('Text:', message.textBody);
+});
+
+jmapClient.on('error', (error: Error) => {
+  console.error('JMAP error:', error);
+});
+
+jmapClient.on('disconnected', () => {
+  console.log('Disconnected');
+});
+
+await jmapClient.connect();
+```
+
+### The Message Shape
+
+Every `message` event (and the query/get helpers) delivers an `ISmartJmapMessage` with resolved bodies:
+
+```typescript
+jmapClient.on('message', (message: ISmartJmapMessage) => {
+  message.id;          // JMAP Email id
+  message.blobId;      // blob id of the raw RFC 5322 message
+  message.threadId;    // JMAP Thread id
+  message.mailboxIds;  // { [mailboxId]: true }
+  message.keywords;    // { '$seen': true, ... }
+  message.from;        // IJmapEmailAddress[]
+  message.to;          // IJmapEmailAddress[] (cc, bcc, replyTo likewise)
+  message.subject;     // string | undefined
+  message.receivedAt;  // ISO date string
+  message.textBody;    // plain-text body, resolved from bodyValues
+  message.htmlBody;    // HTML body, undefined when the email has no text/html part
+  message.attachments; // IJmapAttachment[]: { blobId, name, type, size }
+  message.raw;         // the full raw JMAP Email object
+});
+```
+
+### Querying and Reading Mail
+
+```typescript
+// All mailboxes of the account
+const mailboxes = await jmapClient.getMailboxes();
+
+// Emails in the watched mailbox, newest first (default filter)
+const messages = await jmapClient.queryEmails();
+
+// Custom JMAP filter (RFC 8621 §4.4.1) and limit
+const invoices = await jmapClient.queryEmails({ subject: 'Invoice' }, 10);
+
+// Single email with all body values fetched (fetchAllBodyValues)
+const message = await jmapClient.getEmail(messages[0].id);
+```
+
+### Flags and Keywords
+
+```typescript
+// Convenience: set the $seen keyword
+await jmapClient.markSeen(message.id);
+
+// Replace the full keywords object
+await jmapClient.setKeywords(message.id, { $seen: true, $flagged: true });
+```
+
+### Sending Mail
+
+`sendEmail` looks up the account's identities via `Identity/get`, creates the email via `Email/set` (stored in the mailbox with role `sent`, falling back to `drafts`, then the watched mailbox), and submits it via `EmailSubmission/set`:
+
+```typescript
+const result = await jmapClient.sendEmail({
+  to: [{ email: 'friend@example.com' }],
+  subject: 'Hello from JMAP',
+  textBody: 'Plain-text content',
+  htmlBody: '<p>HTML content</p>', // optional
+});
+console.log(result.emailId, result.submissionId);
+```
+
+When `from` is omitted, the first identity of the account is used.
+
+### Downloading Blobs
+
+Raw messages and attachments are blobs; download them via the session's download URL template:
+
+```typescript
+// the raw RFC 5322 message
+const rawBytes = await jmapClient.downloadBlob(message.blobId, 'message/rfc822', 'message.eml');
+
+// an attachment
+for (const attachment of message.attachments) {
+  const bytes = await jmapClient.downloadBlob(attachment.blobId, attachment.type, attachment.name);
+  console.log(attachment.name, bytes.length);
+}
+```
+
+### Raw JMAP Method Calls
+
+For anything not covered by the helpers, `request` sends raw JMAP method calls (RFC 8620 §3.2) and returns the method responses:
+
+```typescript
+const methodResponses = await jmapClient.request([
+  ['Mailbox/query', { accountId: 'account-id', filter: { role: 'archive' } }, 'q0'],
+]);
+```
+
+### Disconnecting
+
+```typescript
+await jmapClient.disconnect();
+```
+
+`disconnect()` tears down the event stream and any polling timer — no handles are left open — and emits `disconnected`.
+
+### The Bundled Test Server
+
+`JmapServer` is a minimal in-memory JMAP server for offline tests. It serves the session resource at `/.well-known/jmap` (and `/jmap/session`), the API at `/jmap/api`, blob downloads, and StateChange pushes via SSE at `/jmap/eventsource`. It validates Bearer and Basic auth and answers unauthenticated requests with `401` + `WWW-Authenticate`.
+
+```typescript
+import { JmapClient, JmapServer } from '@push.rocks/smartjmap';
+
+const jmapServer = new JmapServer();
+jmapServer.addUser('testuser', 'testpass');
+jmapServer.addBearerToken('testuser', 'test-token');
+jmapServer.createMailbox('testuser', 'INBOX', 'inbox');
+jmapServer.addEmail('testuser', 'INBOX', {
+  from: { email: 'alice@example.com' },
+  to: { email: 'testuser@example.com' },
+  subject: 'Welcome',
+  textBody: 'Hello from the test server!',
+});
+
+const port = await jmapServer.start(0); // resolves with the bound port
+
+const client = new JmapClient({
+  sessionUrl: `http://127.0.0.1:${port}/.well-known/jmap`,
+  auth: { accessToken: 'test-token' },
+});
+client.on('message', (message) => console.log(message.subject));
+await client.connect();
+
+// Emails added while a client is connected are pushed via SSE:
+jmapServer.addEmail('testuser', 'INBOX', {
+  from: { email: 'bob@example.com' },
+  to: { email: 'testuser@example.com' },
+  subject: 'Live push',
+  textBody: 'Delivered through the event stream.',
+});
+
+await client.disconnect();
+await jmapServer.stop(); // closes the server and destroys open connections
+```
+
+The dispatched methods are `Core/echo`, `Mailbox/get`, `Mailbox/query`, `Email/get`, `Email/query`, `Email/changes`, `Email/set`, `Identity/get`, and `EmailSubmission/set` — enough for every public `JmapClient` method to run offline.
+
+### Error Handling
+
+`connect()` never throws; failures (unreachable host, wrong credentials, missing capabilities) are emitted as `error` events, and the instance holds no open sockets or timers afterwards. HTTP problem details (RFC 7807) and JMAP method-level errors are surfaced as `JmapError` with `httpStatus`, `problemType`, `problemDetail`, `jmapErrorType`, and `jmapErrorDescription` fields.
+
+Because JMAP is stateless HTTP, the same client instance can reconnect — call `connect()` again after a failure. Already-emitted messages are deduplicated, so a reconnect does not re-emit mail the client has already seen. While connected, the client recovers on its own: if the event stream drops, it silently falls back to `Email/changes` polling, and a `cannotCalculateChanges` response triggers a full re-query.
+
+```typescript
+import { JmapClient, JmapError } from '@push.rocks/smartjmap';
+
+const client = new JmapClient({
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  auth: { accessToken: 'my-api-token' },
+});
+
+client.on('error', (error: Error) => {
+  if (error instanceof JmapError && error.httpStatus === 401) {
+    console.error('Credentials rejected — refresh the token before reconnecting.');
+    return;
+  }
+  console.error('JMAP error, retrying in 10s:', error.message);
+  setTimeout(() => {
+    client.connect().catch(console.error);
+  }, 10000);
+});
+
+await client.connect();
+```
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## License and Legal Information
+
+This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+
+### Company Information
+
+Task Venture Capital GmbH  
+Registered at District court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@push.rocks/smartjmap',
+  version: '1.0.0',
+  description: 'A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.'
+}