@photon-ai/advanced-imessage-kit 1.14.2 → 1.16.0

package/README.md

@@ -14,7 +14,23 @@
 
 Advanced iMessage Kit is a full-featured iMessage SDK for **reading**, **sending**, and **automating** iMessage conversations on macOS. Perfect for building **AI agents**, **automation tools**, and **chat applications**.
 
----
+## Enterprise
+
+**Advanced iMessage Kit** is the **enterprise edition** provided by **[Photon](https://photon.codes)**.
+
+- **Provisioned iMessage Numbers** – Dedicated numbers ready for production use
+- **Managed Hosting** – Fully managed infrastructure for reliability and scale  
+- **DevOps & Deployment Support** – Production setup, monitoring, and scaling  
+- **Enterprise Support** – Direct support and custom integrations  
+
+📩 **Enterprise inquiries:**  
+Contact **daniel@photon.codes**
+
+🌐 **Book a Demo:**  
+https://photon.codes
+
+If you're looking for the **free/open-source version**, please use **[iMessage Kit](https://github.com/photon-hq/imessage-kit)** instead.
+
 
 ## Features
 
@@ -23,6 +39,8 @@ Advanced iMessage Kit is a full-featured iMessage SDK for **reading**, **sending
 | [Send Messages](#send-messages)                            | Send text messages to any contact             | `messages.sendMessage()`                     | [message-send.ts](./examples/message-send.ts)                                   |
 | [Reply to Messages](#send-messages)                        | Reply inline to a specific message            | `messages.sendMessage()`                     | [message-reply.ts](./examples/message-reply.ts)                                 |
 | [Message Effects](#send-messages)                          | Send with effects (confetti, fireworks, etc.) | `messages.sendMessage()`                     | [message-effects.ts](./examples/message-effects.ts)                             |
+| [Text Styles](#text-styles--animations)                    | Bold, italic, underline, strikethrough        | `messages.sendMessage()`                     | [message-styled.ts](./examples/message-styled.ts)                               |
+| [Text Animations](#text-styles--animations)                | Per-character animations (shake, ripple, etc.)| `messages.sendMessage()`                     | [message-styled.ts](./examples/message-styled.ts)                               |
 | [Send Rich Links](#send-messages)                          | Send URLs with rich link previews             | `messages.sendMessage()`                     | [message-rich-link.ts](./examples/message-rich-link.ts)                         |
 | [Schedule Messages](#scheduled-messages)                   | Send once or on a recurring schedule          | `scheduledMessages.createScheduledMessage()` | [scheduled-message-once.ts](./examples/scheduled-message-once.ts)               |
 | [Unsend Messages](#unsend-messages)                        | Retract a sent message                        | `messages.unsendMessage()`                   | [message-unsend.ts](./examples/message-unsend.ts)                               |
@@ -49,6 +67,7 @@ Advanced iMessage Kit is a full-featured iMessage SDK for **reading**, **sending
 | [Vote on Polls](#vote-on-polls)                            | Vote or unvote on poll options                | `polls.vote()`                               | [poll-vote.ts](./examples/poll-vote.ts)                                         |
 | [Add Poll Options](#add-poll-options)                      | Add options to existing polls                 | `polls.addOption()`                          | [poll-add-option.ts](./examples/poll-add-option.ts)                             |
 | [Find My Friends](#find-my-friends)                        | Get friends' locations                        | `icloud.refreshFindMyFriends()`              | [findmy-friends.ts](./examples/findmy-friends.ts)                               |
+| [Find My Watch](#find-my-watch)                            | Watch friends' location changes in real-time  | `icloud.refreshFindMyFriends()`              | [findmy-watch.ts](./examples/findmy-watch.ts)                                   |
 | [Set Chat Background](#chat-background)                    | Set custom background image for chat          | `chats.setBackground()`                      | [background-set.ts](./examples/background-set.ts)                               |
 | [Remove Chat Background](#chat-background)                 | Remove background from chat                   | `chats.removeBackground()`                   | [background-remove.ts](./examples/background-remove.ts)                         |
 | [Real-time Events](#real-time-events)                      | Listen for new messages, typing, etc.         | `sdk.on()`                                   | [listen-simple.ts](./examples/listen-simple.ts)                                 |
@@ -100,6 +119,15 @@ interface ClientConfig {
 }
 ```
 
+### Remote Server Setup
+
+If your SDK code runs on a different machine than the iMessage server:
+
+- `serverUrl` points to the server machine
+- `filePath` points to the SDK machine
+
+The SDK reads local files first, then uploads the file bytes to the server.
+
 ---
 
 ## Core Concepts
@@ -190,6 +218,71 @@ await sdk.messages.sendMessage({
 
 > Example: [message-effects.ts](./examples/message-effects.ts)
 
+### Text Styles & Animations
+
+Apply per-range text formatting and whole-message character animations (requires Private API):
+
+```typescript
+// Bold a portion of text
+await sdk.messages.sendMessage({
+  chatGuid: "iMessage;-;+1234567890",
+  message: "This is bold text",
+  textStyles: [{ start: 8, end: 12, bold: true }],
+});
+
+// Multiple styles in one message
+await sdk.messages.sendMessage({
+  chatGuid: "iMessage;-;+1234567890",
+  message: "Bold here, italic there",
+  textStyles: [
+    { start: 0, end: 9, bold: true },
+    { start: 11, end: 23, italic: true },
+  ],
+});
+
+// Character animation (applies to whole message)
+await sdk.messages.sendMessage({
+  chatGuid: "iMessage;-;+1234567890",
+  message: "Ripple wave!",
+  textAnimation: "ripple",
+});
+
+// Combine all three layers
+await sdk.messages.sendMessage({
+  chatGuid: "iMessage;-;+1234567890",
+  message: "Bold shaking fireworks!",
+  textStyles: [{ start: 0, end: 4, bold: true }],
+  textAnimation: "shake",
+  effectId: "com.apple.messages.effect.CKFireworksEffect",
+});
+```
+
+**Text Style Properties** (per range):
+
+| Property        | Type    | Description    |
+| --------------- | ------- | -------------- |
+| `start`         | number  | Start index    |
+| `end`           | number  | End index      |
+| `bold`          | boolean | Bold           |
+| `italic`        | boolean | Italic         |
+| `underline`     | boolean | Underline      |
+| `strikethrough` | boolean | Strikethrough  |
+
+**Text Animations** (whole message):
+
+| `textAnimation` | Description |
+| --------------- | ----------- |
+| `"big"`         | Big         |
+| `"small"`       | Small       |
+| `"shake"`       | Shake       |
+| `"nod"`         | Nod         |
+| `"explode"`     | Explode     |
+| `"ripple"`      | Ripple      |
+| `"bloom"`       | Bloom       |
+| `"jitter"`      | Jitter      |
+
+> Example: [message-styled.ts](./examples/message-styled.ts)
+
 ### Query Messages
 
 ```typescript
@@ -337,7 +430,7 @@ const updated = await sdk.scheduledMessages.updateScheduledMessage(
     },
     scheduledFor: Date.now() + 10 * 60 * 1000,
     schedule: { type: "once" },
-  }
+  },
 );
 
 await sdk.scheduledMessages.deleteScheduledMessage("scheduled-id");
@@ -528,6 +621,38 @@ const message = await sdk.attachments.sendAttachment({
 });
 ```
 
+### Send Multiple Images In One Request
+
+Use `sendMultipartMessage()` when you want to send multiple images together as one multipart iMessage request:
+
+```typescript
+const message = await sdk.messages.sendMultipartMessage({
+  chatGuid: "iMessage;+;chat123456789",
+  parts: [
+    {
+      partIndex: 0,
+      filePath: "/path/to/image-1.jpg",
+    },
+    {
+      partIndex: 1,
+      filePath: "/path/to/image-2.jpg",
+    },
+    {
+      partIndex: 2,
+      filePath: "/path/to/image-3.jpg",
+    },
+  ],
+});
+```
+
+Notes:
+- `sendMultipartMessage()` uploads each file first, then sends all parts together in a single `/api/v1/message/multipart` request.
+- This requires the Private API path on the server.
+- The target `chatGuid` must already exist. If you only have a phone number/email, create or fetch the chat first.
+- If the SDK and server are on different machines, each `filePath` must exist on the SDK machine. The SDK uploads the file bytes to the server before sending.
+
+> Example: [message-multipart-images.ts](./examples/message-multipart-images.ts)
+
 ### Send Audio Messages
 
 ```typescript
@@ -595,9 +720,8 @@ const buffer = await sdk.attachments.downloadAttachment("attachment-guid", {
 });
 
 // Download Live Photo video
-const liveBuffer = await sdk.attachments.downloadAttachmentLive(
-  "attachment-guid"
-);
+const liveBuffer =
+  await sdk.attachments.downloadAttachmentLive("attachment-guid");
 
 // Get blurhash (for placeholders)
 const blurhash = await sdk.attachments.getAttachmentBlurhash("attachment-guid");
@@ -686,11 +810,11 @@ Check if a phone/email supports iMessage or FaceTime:
 // First parameter is the address (phone or email), not handle guid
 const hasIMessage = await sdk.handles.getHandleAvailability(
   "+1234567890",
-  "imessage"
+  "imessage",
 );
 const hasFaceTime = await sdk.handles.getHandleAvailability(
   "+1234567890",
-  "facetime"
+  "facetime",
 );
 
 // Choose service based on availability
@@ -852,7 +976,7 @@ sdk.on("new-message", (message) => {
 
 ## iCloud
 
-> Example: [findmy-friends.ts](./examples/findmy-friends.ts)
+> Examples: [findmy-friends.ts](./examples/findmy-friends.ts) | [findmy-watch.ts](./examples/findmy-watch.ts)
 
 ### Find My Friends
 
@@ -870,10 +994,10 @@ const locations = await sdk.icloud.refreshFindMyFriends();
 const friend = locations.find((loc) => loc.handle === "+1234567890");
 if (friend) {
   console.log(
-    `Coordinates: ${friend.coordinates[0]}, ${friend.coordinates[1]}`
+    `Coordinates: ${friend.coordinates[0]}, ${friend.coordinates[1]}`,
   );
   console.log(
-    `Maps: https://maps.google.com/?q=${friend.coordinates[0]},${friend.coordinates[1]}`
+    `Maps: https://maps.google.com/?q=${friend.coordinates[0]},${friend.coordinates[1]}`,
   );
   if (friend.long_address) console.log(`Address: ${friend.long_address}`);
 }
@@ -887,6 +1011,37 @@ for (const loc of locations) {
 
 > Example: [findmy-friends.ts](./examples/findmy-friends.ts)
 
+### Find My Watch
+
+Watch friends' location changes in real-time. Fetches initial locations on connect, then listens for live updates via the `new-findmy-location` event (server auto-refreshes every 30s):
+
+```typescript
+import type { FindMyLocationItem } from "@photon-ai/advanced-imessage-kit";
+
+// Fetch initial locations on ready
+sdk.on("ready", async () => {
+  const locations = await sdk.icloud.refreshFindMyFriends();
+  for (const loc of locations) {
+    console.log(`${loc.handle}`);
+    console.log(`  Coordinates: ${loc.coordinates[0]}, ${loc.coordinates[1]}`);
+    console.log(
+      `  Maps: https://maps.google.com/?q=${loc.coordinates[0]},${loc.coordinates[1]}`,
+    );
+    if (loc.long_address) console.log(`  Address: ${loc.long_address}`);
+  }
+});
+
+// Listen for real-time location updates
+sdk.on("new-findmy-location", (location: FindMyLocationItem) => {
+  console.log(`${location.handle} updated:`);
+  console.log(
+    `  Coordinates: ${location.coordinates[0]}, ${location.coordinates[1]}`,
+  );
+});
+```
+
+> Example: [findmy-watch.ts](./examples/findmy-watch.ts)
+
 ---
 
 ## Real-time Events
@@ -1083,8 +1238,9 @@ bun run examples/<filename>.ts
 | [message-unsend.ts](./examples/message-unsend.ts)                               | Unsend messages       |
 | [message-edit.ts](./examples/message-edit.ts)                                   | Edit messages         |
 | [message-reaction.ts](./examples/message-reaction.ts)                           | Send Tapbacks         |
-| [message-effects.ts](./examples/message-effects.ts)                             | Message effects       |
-| [message-search.ts](./examples/message-search.ts)                               | Search messages       |
+| [message-effects.ts](./examples/message-effects.ts)                             | Message effects          |
+| [message-styled.ts](./examples/message-styled.ts)                               | Text styles & animations |
+| [message-search.ts](./examples/message-search.ts)                               | Search messages          |
 | [message-history.ts](./examples/message-history.ts)                             | Message history       |
 | [message-destination-caller-id.ts](./examples/message-destination-caller-id.ts) | Destination caller ID |
 
@@ -1132,6 +1288,7 @@ bun run examples/<filename>.ts
 | [server-info.ts](./examples/server-info.ts)       | Server info and logs |
 | [message-stats.ts](./examples/message-stats.ts)   | Message statistics   |
 | [findmy-friends.ts](./examples/findmy-friends.ts) | Find My Friends      |
+| [findmy-watch.ts](./examples/findmy-watch.ts)     | Find My Watch        |
 | [auto-reply-hey.ts](./examples/auto-reply-hey.ts) | Auto reply bot       |
 
 ---

package/dist/index.cjs

@@ -164,14 +164,16 @@ function extractService(chatGuid) {
   return void 0;
 }
 async function createChatWithMessage(options) {
-  const { http, address, message, tempGuid, subject, effectId, service } = options;
+  const { http, address, message, tempGuid, subject, bubbleEffect, textStyles, textAnimation, service } = options;
   try {
     const response = await http.post("/api/v1/chat/new", {
       addresses: [address],
       message,
       tempGuid,
       subject,
-      effectId,
+      bubbleEffect,
+      textStyles,
+      textAnimation,
       ...service && { service }
     });
     return response.data.data?.guid;
@@ -529,6 +531,15 @@ var MessageModule = class {
     this.http = http;
     this.enqueueSend = enqueueSend;
   }
+  async uploadMultipartAttachment(part, fileName = part.fileName || path__namespace.default.basename(part.filePath)) {
+    const fileBuffer = await promises.readFile(part.filePath);
+    const form = new FormData__default.default();
+    form.append("attachment", fileBuffer, fileName);
+    const response = await this.http.post("/api/v1/attachment/upload", form, {
+      headers: form.getHeaders()
+    });
+    return response.data.data.path;
+  }
   async sendMessage(options) {
     return this.enqueueSend(async () => {
       const tempGuid = options.tempGuid || crypto.randomUUID();
@@ -547,13 +558,70 @@ var MessageModule = class {
           message: options.message,
           tempGuid,
           subject: options.subject,
-          effectId: options.effectId,
+          bubbleEffect: options.bubbleEffect,
+          textStyles: options.textStyles,
+          textAnimation: options.textAnimation,
           service
         });
         return { guid: tempGuid, text: options.message, dateCreated: Date.now() };
       }
     });
   }
+  async sendMultipartMessage(options) {
+    return this.enqueueSend(async () => {
+      const tempGuid = options.tempGuid || crypto.randomUUID();
+      const buildPayloadPart = async (part, index) => {
+        const resolvedPartIndex = part.partIndex ?? index;
+        if ("text" in part) {
+          return {
+            partIndex: resolvedPartIndex,
+            text: part.text,
+            ...part.mention ? { mention: part.mention } : {}
+          };
+        }
+        const fileName = part.fileName || path__namespace.default.basename(part.filePath);
+        const uploadedPath = await this.uploadMultipartAttachment(part, fileName);
+        return {
+          partIndex: resolvedPartIndex,
+          attachment: uploadedPath,
+          name: fileName
+        };
+      };
+      const uploadParts = async () => {
+        const parts = [];
+        for (const [index, part] of options.parts.entries()) {
+          parts.push(await buildPayloadPart(part, index));
+        }
+        return parts;
+      };
+      const send = async (chatGuid) => {
+        const parts = await uploadParts();
+        const payload = {
+          chatGuid,
+          tempGuid,
+          parts,
+          subject: options.subject,
+          effectId: options.effectId,
+          selectedMessageGuid: options.selectedMessageGuid,
+          partIndex: options.partIndex ?? 0,
+          ddScan: options.ddScan ?? false,
+          attributedBody: options.attributedBody
+        };
+        const response = await this.http.post("/api/v1/message/multipart", payload);
+        return response.data.data;
+      };
+      try {
+        return await send(options.chatGuid);
+      } catch (error) {
+        if (isChatNotExistError(error)) {
+          throw new Error(
+            "Chat does not exist for multipart send. Use an existing chatGuid, or create the chat first before calling sendMultipartMessage()."
+          );
+        }
+        throw error;
+      }
+    });
+  }
   async getMessage(guid, options) {
     const response = await this.http.get(`/api/v1/message/${encodeURIComponent(guid)}`, {
       params: options?.with ? { with: options.with.join(",") } : {}
@@ -919,6 +987,7 @@ var _AdvancedIMessageKit = class _AdvancedIMessageKit extends EventEmitter.Event
       "new-server",
       "incoming-facetime",
       "ft-call-status-changed",
+      "new-findmy-location",
       "hello-world"
     ];
     for (const eventName of serverEvents) {