@photon-ai/advanced-imessage-kit 1.3.2 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +109 -54
  2. package/dist/index.cjs +32 -18
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +13 -0
  5. package/dist/index.d.ts +13 -0
  6. package/dist/index.js +32 -18
  7. package/dist/index.js.map +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -18,30 +18,34 @@ Advanced iMessage Kit is a full-featured iMessage SDK for **reading**, **sending
18
18
 
19
19
  ## Features
20
20
 
21
- | Feature | Method | Example |
22
- | ---------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------- |
23
- | [Send Messages](#send-messages) | `messages.sendMessage()` | [message-send.ts](./examples/message-send.ts) |
24
- | [Reply to Messages](#send-messages) | `messages.sendMessage()` | [message-reply.ts](./examples/message-reply.ts) |
25
- | [Message Effects](#send-messages) | `messages.sendMessage()` | [message-effects.ts](./examples/message-effects.ts) |
26
- | [Unsend Messages](#unsend-messages) | `messages.unsendMessage()` | [message-unsend.ts](./examples/message-unsend.ts) |
27
- | [Send Tapbacks](#send-tapbacks) | `messages.sendReaction()` | [message-reaction.ts](./examples/message-reaction.ts) |
28
- | [Query Messages](#query-messages) | `messages.getMessages()` | [message-search.ts](./examples/message-search.ts) |
29
- | [Send Attachments](#send-attachments) | `attachments.sendAttachment()` | [message-attachment.ts](./examples/message-attachment.ts) |
30
- | [Send Audio Messages](#send-audio-messages) | `attachments.sendAttachment()` | [message-audio.ts](./examples/message-audio.ts) |
31
- | [Send Stickers](#send-stickers) | `attachments.sendSticker()` | [message-reply-sticker.ts](./examples/message-reply-sticker.ts) |
32
- | [Download Attachments](#download-attachments) | `attachments.downloadAttachment()` | [attachment-download.ts](./examples/attachment-download.ts) |
33
- | [Get Chats](#get-chats) | `chats.getChats()` | [chat-fetch.ts](./examples/chat-fetch.ts) |
34
- | [Manage Group Chats](#manage-group-chats) | `chats.addParticipant()` | [chat-group.ts](./examples/chat-group.ts) |
35
- | [Typing Indicators](#typing-indicators) | `chats.startTyping()` | [message-typing.ts](./examples/message-typing.ts) |
36
- | [Get Contacts](#get-contacts) | `contacts.getContacts()` | [contact-list.ts](./examples/contact-list.ts) |
37
- | [Check iMessage Availability](#check-service-availability) | `handles.getHandleAvailability()` | [service-check.ts](./examples/service-check.ts) |
38
- | [Server Info](#get-server-info) | `server.getServerInfo()` | [server-info.ts](./examples/server-info.ts) |
39
- | [Message Statistics](#message-statistics) | `server.getMessageStats()` | [message-stats.ts](./examples/message-stats.ts) |
40
- | [Create Polls](#create-polls) | `polls.create()` | [poll-create.ts](./examples/poll-create.ts) |
41
- | [Add Poll Options](#add-poll-options) | `polls.addOption()` | [poll-add-option.ts](./examples/poll-add-option.ts) |
42
- | [Find My Friends](#find-my-friends) _(WIP)_ | `icloud.getFindMyFriends()` | [findmy-friends.ts](./examples/findmy-friends.ts) |
43
- | [Real-time Events](#real-time-events) | `sdk.on()` | [listen-simple.ts](./examples/listen-simple.ts) |
44
- | [Auto Reply](#real-time-events) | `sdk.on()` | [auto-reply-hey.ts](./examples/auto-reply-hey.ts) |
21
+ | Feature | Description | Method | Example |
22
+ | ------- | ----------- | ------ | ------- |
23
+ | [Send Messages](#send-messages) | Send text messages to any contact | `messages.sendMessage()` | [message-send.ts](./examples/message-send.ts) |
24
+ | [Reply to Messages](#send-messages) | Reply inline to a specific message | `messages.sendMessage()` | [message-reply.ts](./examples/message-reply.ts) |
25
+ | [Message Effects](#send-messages) | Send with effects (confetti, fireworks, etc.) | `messages.sendMessage()` | [message-effects.ts](./examples/message-effects.ts) |
26
+ | [Unsend Messages](#unsend-messages) | Retract a sent message | `messages.unsendMessage()` | [message-unsend.ts](./examples/message-unsend.ts) |
27
+ | [Send Tapbacks](#send-tapbacks) | React with ❤️ 👍 👎 😂 ‼️ ❓ | `messages.sendReaction()` | [message-reaction.ts](./examples/message-reaction.ts) |
28
+ | [Query Messages](#query-messages) | Search and filter message history | `messages.getMessages()` | [message-search.ts](./examples/message-search.ts) |
29
+ | [Message History](#get-chat-messages) | View messages, reactions, polls, stickers | `chats.getChatMessages()` | [message-history.ts](./examples/message-history.ts) |
30
+ | [Send Attachments](#send-attachments) | Send images, files, documents | `attachments.sendAttachment()` | [message-attachment.ts](./examples/message-attachment.ts) |
31
+ | [Send Audio Messages](#send-audio-messages) | Send voice messages | `attachments.sendAttachment()` | [message-audio.ts](./examples/message-audio.ts) |
32
+ | [Send Stickers](#send-stickers) | Send sticker as standalone message | `attachments.sendSticker()` | [message-sticker.ts](./examples/message-sticker.ts) |
33
+ | [Reply Stickers](#send-stickers) | Attach sticker to a message bubble | `attachments.sendSticker()` | [message-reply-sticker.ts](./examples/message-reply-sticker.ts) |
34
+ | [Download Attachments](#download-attachments) | Download received files and media | `attachments.downloadAttachment()` | [attachment-download.ts](./examples/attachment-download.ts) |
35
+ | [Get Chats](#get-chats) | List all conversations | `chats.getChats()` | [chat-fetch.ts](./examples/chat-fetch.ts) |
36
+ | [Manage Group Chats](#manage-group-chats) | Add/remove members, rename groups | `chats.addParticipant()` | [chat-group.ts](./examples/chat-group.ts) |
37
+ | [Typing Indicators](#typing-indicators) | Show "typing..." status | `chats.startTyping()` | [message-typing.ts](./examples/message-typing.ts) |
38
+ | [Get Contacts](#get-contacts) | Fetch device contacts | `contacts.getContacts()` | [contact-list.ts](./examples/contact-list.ts) |
39
+ | [Share Contact Card](#share-contact-card) | Share your contact info in chat | `contacts.shareContactCard()` | [message-contact-card.ts](./examples/message-contact-card.ts) |
40
+ | [Check iMessage Availability](#check-service-availability) | Verify if contact uses iMessage | `handles.getHandleAvailability()` | [service-check.ts](./examples/service-check.ts) |
41
+ | [Server Info](#get-server-info) | Get server status and config | `server.getServerInfo()` | [server-info.ts](./examples/server-info.ts) |
42
+ | [Message Statistics](#message-statistics) | Get message counts and analytics | `server.getMessageStats()` | [message-stats.ts](./examples/message-stats.ts) |
43
+ | [Create Polls](#create-polls) | Create interactive polls in chat | `polls.create()` | [poll-create.ts](./examples/poll-create.ts) |
44
+ | [Vote on Polls](#vote-on-polls) | Vote or unvote on poll options | `polls.vote()` | [poll-create.ts](./examples/poll-create.ts) |
45
+ | [Add Poll Options](#add-poll-options) | Add options to existing polls | `polls.addOption()` | [poll-add-option.ts](./examples/poll-add-option.ts) |
46
+ | [Find My Friends](#find-my-friends) _(WIP)_ | Get friends' locations | `icloud.getFindMyFriends()` | [findmy-friends.ts](./examples/findmy-friends.ts) |
47
+ | [Real-time Events](#real-time-events) | Listen for new messages, typing, etc. | `sdk.on()` | [listen-simple.ts](./examples/listen-simple.ts) |
48
+ | [Auto Reply](#real-time-events) | Build automated reply bots | `sdk.on()` | [auto-reply-hey.ts](./examples/auto-reply-hey.ts) |
45
49
 
46
50
  ---
47
51
 
@@ -378,11 +382,31 @@ const message = await sdk.attachments.sendAttachment({
378
382
 
379
383
  ### Send Stickers
380
384
 
385
+ Stickers can be sent in two ways:
386
+
387
+ **Standalone Sticker** - Sends as its own message (like sending an image, but with sticker styling):
388
+
381
389
  ```typescript
382
390
  await sdk.attachments.sendSticker({
383
391
  chatGuid: "iMessage;-;+1234567890",
384
392
  filePath: "/path/to/sticker.png",
385
- selectedMessageGuid: "message-to-stick-on", // Optional
393
+ });
394
+ ```
395
+
396
+ > Example: [message-sticker.ts](./examples/message-sticker.ts)
397
+
398
+ **Reply Sticker (Tapback Sticker)** - Attaches to an existing message bubble:
399
+
400
+ ```typescript
401
+ await sdk.attachments.sendSticker({
402
+ chatGuid: "iMessage;-;+1234567890",
403
+ filePath: "/path/to/sticker.png",
404
+ selectedMessageGuid: "target-message-guid", // Required for reply sticker
405
+ stickerX: 0.5, // Position X (0-1), default: 0.5
406
+ stickerY: 0.5, // Position Y (0-1), default: 0.5
407
+ stickerScale: 0.75, // Scale (0-1), default: 0.75
408
+ stickerRotation: 0, // Rotation in radians, default: 0
409
+ stickerWidth: 300, // Width in pixels, default: 300
386
410
  });
387
411
  ```
388
412
 
@@ -436,10 +460,32 @@ const contacts = await sdk.contacts.getContacts();
436
460
  ### Get Contact Card
437
461
 
438
462
  ```typescript
439
- // Get by phone or email
463
+ // Get contact card by phone or email
440
464
  const card = await sdk.contacts.getContactCard("+1234567890");
465
+ // {
466
+ // firstName: "John",
467
+ // lastName: "Doe",
468
+ // emails: ["john@example.com"],
469
+ // phones: ["+1234567890"],
470
+ // ...
471
+ // }
472
+ ```
473
+
474
+ ### Share Contact Card
475
+
476
+ Share your contact card with a chat:
477
+
478
+ ```typescript
479
+ // Check if sharing is recommended
480
+ const shouldShare = await sdk.contacts.shouldShareContact("chat-guid");
481
+ // Returns false if you've already shared or they haven't shared theirs
482
+
483
+ // Share your contact card
484
+ await sdk.contacts.shareContactCard("chat-guid");
441
485
  ```
442
486
 
487
+ > Example: [message-contact-card.ts](./examples/message-contact-card.ts)
488
+
443
489
  ---
444
490
 
445
491
  ## Handles
@@ -543,18 +589,6 @@ const chatMediaStats = await sdk.server.getMediaStatisticsByChat();
543
589
  const logs = await sdk.server.getServerLogs(100); // Get last 100 logs
544
590
  ```
545
591
 
546
- ### Alert Management
547
-
548
- ```typescript
549
- // Get alerts
550
- const alerts = await sdk.server.getAlerts();
551
-
552
- // Mark alerts as read
553
- await sdk.server.markAlertAsRead(["alert-id-1", "alert-id-2"]);
554
- ```
555
-
556
- > Example: [server-info.ts](./examples/server-info.ts)
557
-
558
592
  ---
559
593
 
560
594
  ## Polls
@@ -587,6 +621,24 @@ await sdk.polls.addOption({
587
621
 
588
622
  > Example: [poll-add-option.ts](./examples/poll-add-option.ts)
589
623
 
624
+ ### Vote on Polls
625
+
626
+ ```typescript
627
+ // Vote on a poll option
628
+ await sdk.polls.vote({
629
+ chatGuid: "iMessage;-;+1234567890",
630
+ pollMessageGuid: "poll-message-guid",
631
+ optionIdentifier: "option-uuid", // UUID of the option to vote for
632
+ });
633
+
634
+ // Remove your vote
635
+ await sdk.polls.unvote({
636
+ chatGuid: "iMessage;-;+1234567890",
637
+ pollMessageGuid: "poll-message-guid",
638
+ optionIdentifier: "option-uuid",
639
+ });
640
+ ```
641
+
590
642
  ### Parse Poll Messages
591
643
 
592
644
  Use the `poll-utils` helper functions to parse and display poll messages:
@@ -836,36 +888,39 @@ bun run examples/<filename>.ts
836
888
 
837
889
  ### Message Operations
838
890
 
839
- | File | Description |
840
- | ----------------------------------------------------- | ----------------- |
841
- | [message-reply.ts](./examples/message-reply.ts) | Reply to messages |
842
- | [message-unsend.ts](./examples/message-unsend.ts) | Unsend messages |
843
- | [message-reaction.ts](./examples/message-reaction.ts) | Send Tapbacks |
844
- | [message-effects.ts](./examples/message-effects.ts) | Message effects |
845
- | [message-search.ts](./examples/message-search.ts) | Search messages |
891
+ | File | Description |
892
+ | ----------------------------------------------------- | ------------------ |
893
+ | [message-reply.ts](./examples/message-reply.ts) | Reply to messages |
894
+ | [message-unsend.ts](./examples/message-unsend.ts) | Unsend messages |
895
+ | [message-reaction.ts](./examples/message-reaction.ts) | Send Tapbacks |
896
+ | [message-effects.ts](./examples/message-effects.ts) | Message effects |
897
+ | [message-search.ts](./examples/message-search.ts) | Search messages |
898
+ | [message-history.ts](./examples/message-history.ts) | Message history |
846
899
 
847
900
  ### Chats & Groups
848
901
 
849
- | File | Description |
850
- | ------------------------------------------------- | ----------------- |
851
- | [chat-fetch.ts](./examples/chat-fetch.ts) | Get chat list |
852
- | [chat-group.ts](./examples/chat-group.ts) | Manage groups |
853
- | [message-typing.ts](./examples/message-typing.ts) | Typing indicators |
902
+ | File | Description |
903
+ | ----------------------------------------------------- | ------------------- |
904
+ | [chat-fetch.ts](./examples/chat-fetch.ts) | Get chat list |
905
+ | [chat-group.ts](./examples/chat-group.ts) | Manage groups |
906
+ | [message-typing.ts](./examples/message-typing.ts) | Typing indicators |
854
907
 
855
908
  ### Contacts & Services
856
909
 
857
910
  | File | Description |
858
911
  | --------------------------------------------------------------- | ----------------------------- |
859
912
  | [contact-list.ts](./examples/contact-list.ts) | Get contacts |
913
+ | [message-contact-card.ts](./examples/message-contact-card.ts) | Share contact card |
860
914
  | [service-check.ts](./examples/service-check.ts) | Check iMessage availability |
861
915
  | [message-service-check.ts](./examples/message-service-check.ts) | Monitor message service types |
862
916
 
863
917
  ### Attachments & Media
864
918
 
865
- | File | Description |
866
- | --------------------------------------------------------------- | -------------------- |
867
- | [attachment-download.ts](./examples/attachment-download.ts) | Download attachments |
868
- | [message-reply-sticker.ts](./examples/message-reply-sticker.ts) | Send stickers |
919
+ | File | Description |
920
+ | --------------------------------------------------------------- | ------------------------- |
921
+ | [attachment-download.ts](./examples/attachment-download.ts) | Download attachments |
922
+ | [message-sticker.ts](./examples/message-sticker.ts) | Send standalone stickers |
923
+ | [message-reply-sticker.ts](./examples/message-reply-sticker.ts) | Send reply stickers |
869
924
 
870
925
  ### Polls
871
926
 
package/dist/index.cjs CHANGED
@@ -144,7 +144,7 @@ var AttachmentModule = class {
144
144
  return response.data.data.total;
145
145
  }
146
146
  async getAttachment(guid) {
147
- const response = await this.http.get(`/api/v1/attachment/${guid}`);
147
+ const response = await this.http.get(`/api/v1/attachment/${encodeURIComponent(guid)}`);
148
148
  return response.data.data;
149
149
  }
150
150
  async downloadAttachment(guid, options) {
@@ -154,14 +154,14 @@ var AttachmentModule = class {
154
154
  if (options?.height !== void 0) params.height = options.height;
155
155
  if (options?.width !== void 0) params.width = options.width;
156
156
  if (options?.quality !== void 0) params.quality = options.quality;
157
- const response = await this.http.get(`/api/v1/attachment/${guid}/download`, {
157
+ const response = await this.http.get(`/api/v1/attachment/${encodeURIComponent(guid)}/download`, {
158
158
  params,
159
159
  responseType: "arraybuffer"
160
160
  });
161
161
  return Buffer.from(response.data);
162
162
  }
163
163
  async downloadAttachmentLive(guid) {
164
- const response = await this.http.get(`/api/v1/attachment/${guid}/live`, {
164
+ const response = await this.http.get(`/api/v1/attachment/${encodeURIComponent(guid)}/live`, {
165
165
  responseType: "arraybuffer"
166
166
  });
167
167
  return Buffer.from(response.data);
@@ -171,7 +171,7 @@ var AttachmentModule = class {
171
171
  if (options?.height !== void 0) params.height = options.height;
172
172
  if (options?.width !== void 0) params.width = options.width;
173
173
  if (options?.quality !== void 0) params.quality = options.quality;
174
- const response = await this.http.get(`/api/v1/attachment/${guid}/blurhash`, {
174
+ const response = await this.http.get(`/api/v1/attachment/${encodeURIComponent(guid)}/blurhash`, {
175
175
  params
176
176
  });
177
177
  return response.data.data.blurhash;
@@ -212,12 +212,12 @@ var AttachmentModule = class {
212
212
  if (options.selectedMessageGuid) {
213
213
  form.append("selectedMessageGuid", options.selectedMessageGuid);
214
214
  form.append("partIndex", "0");
215
+ form.append("stickerX", String(options.stickerX ?? 0.5));
216
+ form.append("stickerY", String(options.stickerY ?? 0.5));
217
+ form.append("stickerScale", String(options.stickerScale ?? 0.75));
218
+ form.append("stickerRotation", String(options.stickerRotation ?? 0));
219
+ form.append("stickerWidth", String(options.stickerWidth ?? 300));
215
220
  }
216
- form.append("stickerX", String(options.stickerX ?? 0.5));
217
- form.append("stickerY", String(options.stickerY ?? 0.5));
218
- form.append("stickerScale", String(options.stickerScale ?? 0.75));
219
- form.append("stickerRotation", String(options.stickerRotation ?? 0));
220
- form.append("stickerWidth", String(options.stickerWidth ?? 300));
221
221
  const { data } = await this.http.post("/api/v1/message/attachment", form, {
222
222
  headers: form.getHeaders()
223
223
  });
@@ -253,6 +253,9 @@ var ChatModule = class {
253
253
  async markChatRead(guid) {
254
254
  await this.http.post(`/api/v1/chat/${encodeURIComponent(guid)}/read`);
255
255
  }
256
+ async markChatUnread(guid) {
257
+ await this.http.post(`/api/v1/chat/${encodeURIComponent(guid)}/unread`);
258
+ }
256
259
  async leaveChat(guid) {
257
260
  await this.http.post(`/api/v1/chat/${encodeURIComponent(guid)}/leave`);
258
261
  }
@@ -311,6 +314,17 @@ var ChatModule = class {
311
314
  async stopTyping(chatGuid) {
312
315
  await this.http.delete(`/api/v1/chat/${encodeURIComponent(chatGuid)}/typing`);
313
316
  }
317
+ async getBackground(chatGuid) {
318
+ const response = await this.http.get(`/api/v1/chat/${encodeURIComponent(chatGuid)}/background`);
319
+ return response.data.data;
320
+ }
321
+ async setBackground(chatGuid, options) {
322
+ const body = typeof options === "string" ? { imageUrl: options } : options;
323
+ await this.http.post(`/api/v1/chat/${encodeURIComponent(chatGuid)}/background`, body);
324
+ }
325
+ async removeBackground(chatGuid) {
326
+ await this.http.delete(`/api/v1/chat/${encodeURIComponent(chatGuid)}/background`);
327
+ }
314
328
  };
315
329
 
316
330
  // modules/contact.ts
@@ -370,7 +384,7 @@ var HandleModule = class {
370
384
  };
371
385
  }
372
386
  async getHandle(guid) {
373
- const response = await this.http.get(`/api/v1/handle/${guid}`);
387
+ const response = await this.http.get(`/api/v1/handle/${encodeURIComponent(guid)}`);
374
388
  return response.data.data;
375
389
  }
376
390
  async getHandleAvailability(address, type) {
@@ -380,7 +394,7 @@ var HandleModule = class {
380
394
  return response.data.data.available;
381
395
  }
382
396
  async getHandleFocusStatus(guid) {
383
- const response = await this.http.get(`/api/v1/handle/${guid}/focus`);
397
+ const response = await this.http.get(`/api/v1/handle/${encodeURIComponent(guid)}/focus`);
384
398
  return response.data.data.status;
385
399
  }
386
400
  };
@@ -461,7 +475,7 @@ var MessageModule = class {
461
475
  });
462
476
  }
463
477
  async getMessage(guid, options) {
464
- const response = await this.http.get(`/api/v1/message/${guid}`, {
478
+ const response = await this.http.get(`/api/v1/message/${encodeURIComponent(guid)}`, {
465
479
  params: options?.with ? { with: options.with.join(",") } : {}
466
480
  });
467
481
  return response.data.data;
@@ -506,7 +520,7 @@ var MessageModule = class {
506
520
  }
507
521
  async editMessage(options) {
508
522
  return this.enqueueSend(async () => {
509
- const response = await this.http.post(`/api/v1/message/${options.messageGuid}/edit`, {
523
+ const response = await this.http.post(`/api/v1/message/${encodeURIComponent(options.messageGuid)}/edit`, {
510
524
  editedMessage: options.editedMessage,
511
525
  backwardsCompatibilityMessage: options.backwardsCompatibilityMessage || options.editedMessage,
512
526
  partIndex: options.partIndex ?? 0
@@ -527,17 +541,17 @@ var MessageModule = class {
527
541
  }
528
542
  async unsendMessage(options) {
529
543
  return this.enqueueSend(async () => {
530
- const response = await this.http.post(`/api/v1/message/${options.messageGuid}/unsend`, {
544
+ const response = await this.http.post(`/api/v1/message/${encodeURIComponent(options.messageGuid)}/unsend`, {
531
545
  partIndex: options.partIndex ?? 0
532
546
  });
533
547
  return response.data.data;
534
548
  });
535
549
  }
536
550
  async notifyMessage(guid) {
537
- await this.http.post(`/api/v1/message/${guid}/notify`);
551
+ await this.http.post(`/api/v1/message/${encodeURIComponent(guid)}/notify`);
538
552
  }
539
553
  async getEmbeddedMedia(guid) {
540
- const response = await this.http.get(`/api/v1/message/${guid}/embedded-media`);
554
+ const response = await this.http.get(`/api/v1/message/${encodeURIComponent(guid)}/embedded-media`);
541
555
  return response.data.data;
542
556
  }
543
557
  async searchMessages(options) {
@@ -605,11 +619,11 @@ var ScheduledMessageModule = class {
605
619
  return response.data.data;
606
620
  }
607
621
  async updateScheduledMessage(id, options) {
608
- const response = await this.http.put(`/api/v1/message/schedule/${id}`, options);
622
+ const response = await this.http.put(`/api/v1/message/schedule/${encodeURIComponent(id)}`, options);
609
623
  return response.data.data;
610
624
  }
611
625
  async deleteScheduledMessage(id) {
612
- await this.http.delete(`/api/v1/message/schedule/${id}`);
626
+ await this.http.delete(`/api/v1/message/schedule/${encodeURIComponent(id)}`);
613
627
  }
614
628
  };
615
629