@photon-ai/advanced-imessage-kit 1.14.3 → 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)                               |
@@ -101,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
@@ -191,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
@@ -529,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
@@ -1114,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 |
 

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(",") } : {}