pronto-imessage 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# pronto-imessage
+
+`pronto-imessage` is Pronto's reusable, in-process interface to local Apple Messages on macOS. It owns the `imsg` JSON-RPC child process, capability qualification, provider-event normalization, watch notifications, exact-chat reply routing, and local delivery outcomes. It does not launch agents, interpret activation tags, or grant access to consumer resources.
+
+```ts
+import { createProntoMessages } from "pronto-imessage";
+
+const messages = createProntoMessages({
+  imsgPath: "/opt/homebrew/bin/imsg",
+  // Use an owner-private stable value of at least 32 bytes when queued work
+  // must retain an exact conversation reference across a process restart.
+  referenceKey: process.env.PRONTO_MESSAGES_REFERENCE_KEY,
+  statePath: "/private/application-state/provider-state.json",
+});
+await messages.qualify();
+
+const subscription = await messages.subscribe({
+  onEvent: async (event) => {
+    if (event.message.fromMe) return;
+    const page = await messages.history({
+      conversation: event.conversation,
+      budget: {
+        maxMessages: 30,
+        maxRows: 30,
+        maxBytes: 2 * 1024 * 1024,
+        maxRpcCalls: 1,
+      },
+      mode: "recent",
+      includeReactions: true,
+    });
+    await messages.reply({
+      conversation: event.conversation,
+      text: `Reply to this exact conversation (${page.messages.length} context rows)`,
+    });
+  },
+  onRecovery: async (outcome) => {
+    if (outcome.status === "degraded") {
+      // Continue with live events and surface outcome.reason to the owner.
+    }
+  },
+});
+```
+
+The package binds durable checkpoints to a fingerprint of the current Messages database. It restarts and resubscribes after provider failure, performs catch-up within row-count, age, and wall-clock limits, and reports privacy-safe recovery diagnostics. A send that may have reached the provider is returned as `ambiguous` and is never automatically replayed.
+
+Every observed conversation carries a module-issued, versioned, tamper-evident reference with an expiry. References are process-local by default. A consumer with durable queued work can provide a stable owner-private `referenceKey` of at least 32 bytes; that permits an unexpired observed reference to be revalidated after restart without granting access to a different chat. Rotating the key invalidates outstanding references. History requires that exact reference plus an explicit message, row, byte, and RPC-call budget. Pagination continuations remain bound to the same conversation capability and database generation. They cannot be used to search another conversation.
+
+Attachment metadata never exposes the Messages source path. Available attachments carry an expiring sealed reference. `materializeAttachment` revalidates the conversation, database generation, provider metadata, containment under the Messages attachments root, regular-file identity, size, and MIME evidence before copying bytes into owner-private scratch. The returned scratch file has an explicit `dispose()` lifecycle.
+
+The package root exposes normalized, versioned provider facts and delivery outcomes. Raw JSON-RPC methods, database paths, and payloads remain internal. The package is standard ESM and supports current Node.js and Bun consumers; the standalone `pronto` CLI is one ordinary workspace consumer.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { CreateProntoMessagesOptions, ProntoMessages } from "./types.js";
+export type { ConversationFacts, ConversationReference, AttachmentReference, CreateProntoMessagesOptions, DeliveryOutcome, MessagesAttachment, MessagesEvent, MessagesHistoryBudget, MessagesHistoryPage, MessagesDiagnostics, MessagesQualification, MessagesRecoveryOutcome, MessagesRecoveryLimits, MessagesRecoveryReason, MessagesScopeLimits, MessagesSubscription, ProntoMessages, MaterializedAttachment, } from "./types.js";
+export declare function createProntoMessages(input: CreateProntoMessagesOptions): ProntoMessages;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAEV,2BAA2B,EAS3B,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAywBpB,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,2BAA2B,GAAG,cAAc,CAEvF"}