@mapier/imsg-sdk 0.1.0

package/dist/polls.d.ts

@@ -0,0 +1,12 @@
+import type { ImsgMessage, MessagePoll, PollOption } from './types.js';
+export type PollEventKind = 'created' | 'options-changed' | 'vote';
+export declare function pollEventKind(poll: MessagePoll): PollEventKind;
+export declare function pollOriginGuid(msg: ImsgMessage): string | undefined;
+export interface PollSnapshot {
+    originGuid: string;
+    question?: string;
+    options: PollOption[];
+    votesByParticipant: Record<string, string[]>;
+}
+export declare function aggregatePolls(messages: ImsgMessage[]): PollSnapshot[];
+export declare function renderPollEvent(msg: ImsgMessage, history: ImsgMessage[]): string | undefined;

package/dist/polls.js

@@ -0,0 +1,102 @@
+// Vote rows usually carry votes[]; older/edge payloads may only fill vote.
+function pollVotes(poll) {
+    return poll.votes ?? (poll.vote ? [poll.vote] : []);
+}
+// Discriminators surfaced by imsg in poll.metadata: 2 = option update,
+// 4000 = vote. Balloon rows usually read 3 but were observed as 0 right
+// after send (Messages restamps the column) — so classification keys only
+// on kind, type 2, and original_guid, never on the balloon's value.
+export function pollEventKind(poll) {
+    if (poll.kind === 'vote')
+        return 'vote';
+    if (poll.metadata?.associated_message_type === 2 ||
+        (poll.original_guid !== undefined && poll.original_guid !== poll.poll_guid)) {
+        return 'options-changed';
+    }
+    return 'created';
+}
+// The guid of the poll's original balloon row — the join key for question
+// resolution and state aggregation. Original rows carry no original_guid.
+export function pollOriginGuid(msg) {
+    if (!msg.poll)
+        return undefined;
+    return msg.poll.original_guid ?? msg.poll.poll_guid ?? msg.guid;
+}
+// messages must be oldest-first by id — the order history() and the fake
+// store already guarantee.
+export function aggregatePolls(messages) {
+    const byOrigin = new Map();
+    for (const m of messages) {
+        if (!m.poll)
+            continue;
+        const originGuid = pollOriginGuid(m);
+        if (!originGuid)
+            continue;
+        const kind = pollEventKind(m.poll);
+        if (kind === 'created') {
+            byOrigin.set(originGuid, {
+                originGuid,
+                question: m.poll.question,
+                options: m.poll.options ?? [],
+                votesByParticipant: {},
+            });
+            continue;
+        }
+        const snap = byOrigin.get(originGuid);
+        if (!snap)
+            continue; // origin outside this window — nothing to attribute to
+        if (kind === 'options-changed') {
+            if (m.poll.options?.length)
+                snap.options = m.poll.options;
+            continue;
+        }
+        const votes = pollVotes(m.poll);
+        const participant = votes.find((v) => v.participant)?.participant ?? m.sender;
+        if (!participant)
+            continue;
+        snap.votesByParticipant[participant] = votes.map((v) => v.option_id).filter((id) => id !== undefined);
+    }
+    return [...byOrigin.values()];
+}
+function quoteList(texts) {
+    return texts.map((t) => `"${t}"`).join(', ');
+}
+// Render one poll row as a bracketed transcript note, in the voice of the
+// row's sender ("[voted "yes" on the poll …]"). history provides the
+// question join via original_guid; pass just [msg] when no window is at
+// hand and the note degrades to "the poll".
+export function renderPollEvent(msg, history) {
+    const poll = msg.poll;
+    if (!poll)
+        return undefined;
+    const kind = pollEventKind(poll);
+    if (kind === 'created') {
+        const q = poll.question?.trim();
+        const options = (poll.options ?? []).map((o) => o.text);
+        return `[sent a poll${q ? ` "${q}"` : ''} — options: ${quoteList(options)}]`;
+    }
+    const originGuid = pollOriginGuid(msg);
+    const origin = history.find((m) => m.guid === originGuid && m.poll && pollEventKind(m.poll) === 'created');
+    const q = origin?.poll?.question?.trim();
+    const label = q ? `the poll "${q}"` : 'the poll';
+    if (kind === 'vote') {
+        const picked = pollVotes(poll)
+            .map((v) => v.option_text ?? v.option_id)
+            .filter((t) => t !== undefined);
+        if (!picked.length)
+            return `[cleared their vote on ${label}]`;
+        return `[voted ${quoteList(picked)} on ${label}]`;
+    }
+    // options-changed: name the additions when the prior option set is in the
+    // window; otherwise fall back to the full updated list.
+    const prior = history
+        .filter((m) => m.id < msg.id && m.poll && pollOriginGuid(m) === originGuid && pollEventKind(m.poll) !== 'vote')
+        .at(-1);
+    const before = new Set((prior?.poll?.options ?? []).map((o) => o.id));
+    const added = (poll.options ?? []).filter((o) => !before.has(o.id));
+    if (prior && added.length) {
+        return `[added ${added.map((o) => `option "${o.text}"`).join(', ')} to ${label}]`;
+    }
+    return `[updated the options on ${label} to: ${quoteList((poll.options ?? []).map((o) => o.text))}]`;
+}
+//# sourceMappingURL=polls.js.map

package/dist/polls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polls.js","sourceRoot":"","sources":["../src/polls.ts"],"names":[],"mappings":"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"}

package/dist/runtime-report.d.ts

@@ -0,0 +1,3 @@
+export type RuntimeIssueReporter = (code: string) => void;
+export declare function setRuntimeIssueReporter(next: RuntimeIssueReporter): void;
+export declare function reportRuntimeIssue(code: string): void;

package/dist/runtime-report.js

@@ -0,0 +1,10 @@
+let reporter = () => { };
+export function setRuntimeIssueReporter(next) {
+    reporter = next;
+}
+// Intentionally carries a closed code only. Hosted service graphs prohibit
+// ambient output because raw errors can contain message/profile content.
+export function reportRuntimeIssue(code) {
+    reporter(code);
+}
+//# sourceMappingURL=runtime-report.js.map

package/dist/runtime-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-report.js","sourceRoot":"","sources":["../src/runtime-report.ts"],"names":[],"mappings":"AAEA,IAAI,QAAQ,GAAyB,GAAG,EAAE,GAAE,CAAC,CAAC;AAE9C,MAAM,UAAU,uBAAuB,CAAC,IAA0B;IAChE,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,2EAA2E;AAC3E,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,QAAQ,CAAC,IAAI,CAAC,CAAC;AACjB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+export interface MessageReaction {
+    id: number;
+    type: string;
+    emoji?: string;
+    is_from_me: boolean;
+    sender?: string;
+    created_at?: string;
+}
+export interface PollOption {
+    id: string;
+    text: string;
+}
+export interface PollVote {
+    event_type?: string;
+    option_id?: string;
+    option_text?: string;
+    participant?: string;
+    server_time?: string;
+}
+export interface MessagePoll {
+    kind: string;
+    event?: string;
+    question?: string;
+    options?: PollOption[];
+    vote?: PollVote;
+    votes?: PollVote[];
+    creator?: string;
+    participants?: string[];
+    poll_guid?: string;
+    original_guid?: string;
+    metadata?: {
+        associated_message_type?: number;
+    };
+}
+export interface MessageAttachment {
+    filename?: string;
+    original_path?: string;
+    transfer_name?: string;
+    mime_type?: string;
+    uti?: string;
+    total_bytes?: number;
+    missing?: boolean;
+    is_sticker?: boolean;
+}
+export interface ImsgMessage {
+    id: number;
+    chat_id: number;
+    chat_guid?: string;
+    chat_identifier?: string;
+    chat_name?: string;
+    participants?: string[];
+    is_group: boolean;
+    guid: string;
+    sender?: string;
+    sender_name?: string;
+    is_from_me: boolean;
+    text?: string;
+    created_at?: string;
+    reply_to_guid?: string;
+    reactions?: MessageReaction[];
+    attachments?: MessageAttachment[];
+    poll?: MessagePoll;
+    is_reaction?: boolean;
+    reaction_type?: string;
+    reaction_emoji?: string;
+    is_reaction_add?: boolean;
+    reacted_to_guid?: string;
+}
+export interface SendResult {
+    ok: boolean;
+    id?: number;
+    guid?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mapier/imsg-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for iMessage automation on macOS: the Gateway contract, ImsgGateway (real), and a device-free FakeGateway.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mapier-Labs/imsg-sdk.git"
+  },
+  "homepage": "https://github.com/Mapier-Labs/imsg-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Mapier-Labs/imsg-sdk/issues"
+  },
+  "keywords": [
+    "imessage",
+    "macos",
+    "gateway",
+    "sdk",
+    "automation"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.30.3",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "prepublishOnly": "pnpm build && pnpm lint && pnpm typecheck && pnpm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.2",
+    "@types/node": "^24",
+    "tsx": "^4",
+    "typescript": "^5.6"
+  }
+}