fix advanced-imsg-ts docs

Author: qwerzl

advanced-kits/imessage/attachments.mdx

@@ -3,7 +3,7 @@ title: "Attachments"
 description: "Upload, download, and stream file attachments"
 ---
 
-`im.attachments` handles file attachments - uploading before sending, streaming downloads, forcing iCloud downloads, and extracting Live Photos.
+`im.attachments` handles file attachments - uploading before sending, streaming downloads, transparent iCloud recovery, and extracting Live Photos.
 
 ## Supported file types
 
@@ -23,24 +23,41 @@ description: "Upload, download, and stream file attachments"
 
 ## Upload an attachment
 
-Upload a file and get back an `AttachmentGuid` to pass to `im.messages.send()`.
+Upload a file and get back an `AttachmentInfo` object. Use the `guid` property to pass to `im.messages.send()`.
 
 ```ts
-const guid = await im.attachments.upload({
+const info = await im.attachments.upload({
   path: "/path/to/photo.jpg",
-  name: "photo.jpg",       // optional display name
-  mimeType: "image/jpeg",  // optional override
+  fileName: "photo.jpg",      // optional display name
+  mimeType: "image/jpeg",     // optional override
 });
 
-await im.messages.send(chat, "", { attachment: guid });
+await im.messages.send(chat, "", { attachment: info.guid });
 ```
 
+`AttachmentInput` is a union type with two variants - file path or raw bytes:
+
 ```ts
-interface AttachmentInput {
-  path: string;
-  name?: string;
-  mimeType?: string;
-}
+type AttachmentInput =
+  | { data: Uint8Array; fileName: string; mimeType: string }
+  | { path: string; fileName?: string; mimeType?: string };
+```
+
+## Upload a Live Photo
+
+Upload a paired HEIC image + MOV video as a Live Photo:
+
+```ts
+const info = await im.attachments.uploadLivePhoto({
+  image: {
+    data: imageBytes,       // Uint8Array
+    fileName: "photo.heic",
+    mimeType: "image/heic",
+  },
+  video: {
+    data: videoBytes,       // Uint8Array
+  },
+});
 ```
 
 ## Get attachment metadata
@@ -52,22 +69,34 @@ const info = await im.attachments.get(attachmentGuid);
 ```ts
 interface AttachmentInfo {
   guid: AttachmentGuid;
-  originalGuid: string;
-  mimeType?: string;
-  fileName?: string;
+  originalGuid?: AttachmentGuid;
+  mimeType: string;
+  fileName: string;
   totalBytes: number;
   transferState: TransferState;
-  transferName?: string;
+  hasLivePhoto: boolean;
+  height?: number;
+  hideAttachment: boolean;
+  isOutgoing: boolean;
+  isSticker: boolean;
+  uti: string;
+  width?: number;
   _raw?: unknown;
 }
 ```
 
+## Count attachments
+
+```ts
+const total = await im.attachments.count();
+```
+
 ## Download an attachment
 
-`download()` returns a `StreamedDownload` - both a streaming and a buffered consumption path.
+`download()` returns a `StreamedDownload` synchronously - both a streaming and a buffered consumption path.
 
 ```ts
-const dl = await im.attachments.download(attachmentGuid);
+const dl = im.attachments.download(attachmentGuid);
 
 dl.totalBytes;           // file size, known from the first chunk
 
@@ -77,33 +106,33 @@ for await (const chunk of dl.stream) {  // ReadableStream<Uint8Array>
 }
 
 // Or buffer the whole thing
-const buffer = await dl.arrayBuffer();
+const buffer = await dl.arrayBuffer();  // Uint8Array
 ```
 
 ```ts
 interface StreamedDownload {
   totalBytes: number;
   stream: ReadableStream<Uint8Array>;
-  arrayBuffer(): Promise<ArrayBuffer>;
+  arrayBuffer(): Promise<Uint8Array>;
 }
 ```
 
-## Force download from iCloud
+### Quick buffer download
 
-Some attachments are stored in iCloud and not yet on device. Force-download them:
+A convenience method that combines `download()` and `arrayBuffer()`:
 
 ```ts
-await im.attachments.forceDownload(attachmentGuid);
+const bytes = await im.attachments.downloadBuffer(attachmentGuid);
+// bytes: Uint8Array
 ```
 
 ## Live Photos
 
 Extract the video component from a Live Photo attachment:
 
 ```ts
-const video = await im.attachments.getLivePhotoVideo({
-  attachmentGuid,
-  outputPath: "/tmp/live.mov",  // optional - where to write the video
-});
-// video: LivePhotoInput
+const videoDl = im.attachments.getLivePhoto(attachmentGuid);
+const videoBytes = await videoDl.arrayBuffer();
 ```
+
+`getLivePhoto()` returns a `StreamedDownload` synchronously, just like `download()`.

advanced-kits/imessage/chats.mdx

@@ -21,6 +21,16 @@ const { chat, sendReceipt } = await im.chats.create(["+1234567890"], {
 
 `sendReceipt` is present only when an initial `message` was provided.
 
+**`CreateChatOptions`**
+
+| Option | Type | Description |
+|---|---|---|
+| `message` | `string` | Initial message text to send |
+| `service` | `"iMessage" \| "SMS" \| "RCS"` | Service to use |
+| `subject` | `string` | Subject line |
+| `effectId` | `string` | Send effect ID |
+| `clientMessageId` | `string` | Idempotency key |
+
 ### Get a chat
 
 ```ts
@@ -31,13 +41,18 @@ The returned `Chat` object contains:
 
 ```ts
 interface Chat {
-  guid: ChatGuid;
-  displayName?: string;
-  participants: string[];
-  lastMessage?: Message;
-  isArchived: boolean;
-  serviceType: ChatServiceType;
-  _raw?: unknown;
+  readonly guid: ChatGuid;
+  readonly chatIdentifier?: string;
+  readonly displayName?: string;
+  readonly groupId?: string;
+  readonly participants: readonly AddressInfo[];
+  readonly lastMessage?: Message;
+  readonly isArchived: boolean;
+  readonly isFiltered: boolean;
+  readonly isGroup: boolean;
+  readonly service: ChatServiceType;
+  readonly unreadCount?: number;
+  readonly _raw?: unknown;
 }
 ```
 
@@ -52,37 +67,35 @@ const totalWithArchived = await im.chats.count({ includeArchived: true });
 
 ```ts
 // Show typing bubble
-await im.chats.setTyping(chatGuid, true);
+await im.chats.startTyping(chatGuid);
 
 // Stop typing bubble
-await im.chats.setTyping(chatGuid, false);
+await im.chats.stopTyping(chatGuid);
 ```
 
 ### Share contact info
 
 ```ts
-const info = await im.chats.shareContactInfo(chatGuid);
-// info: AddressInfo
+await im.chats.shareContactInfo(chatGuid);
 ```
 
-### Add & remove participants
+### Get participants
 
 ```ts
-await im.chats.addParticipant(chatGuid, "+19998887777");
-await im.chats.removeParticipant(chatGuid, "+19998887777");
+const participants = await im.chats.getParticipants(chatGuid);
+// participants: AddressInfo[]
 ```
 
-### Mark as read
+### Leave a chat
 
 ```ts
-await im.chats.markRead(chatGuid);
+await im.chats.leave(chatGuid);
 ```
 
-### Archive & unarchive
+### Mark as read
 
 ```ts
-await im.chats.setArchived(chatGuid, true);
-await im.chats.setArchived(chatGuid, false);
+await im.chats.markRead(chatGuid);
 ```
 
 ### Real-time chat events
@@ -113,21 +126,25 @@ for await (const event of im.chats.subscribe("chat.typingIndicator")) {
 ### Rename a group
 
 ```ts
-await im.groups.rename(chatGuid, "New Group Name");
+const updatedChat = await im.groups.setDisplayName(chatGuid, "New Group Name");
 ```
 
 ### Manage participants
 
 ```ts
-await im.groups.addParticipant(chatGuid, "newperson@icloud.com");
-await im.groups.removeParticipant(chatGuid, "oldperson@icloud.com");
+const updatedChat = await im.groups.addParticipant(chatGuid, "newperson@icloud.com");
+const updatedChat2 = await im.groups.removeParticipant(chatGuid, "oldperson@icloud.com");
 ```
 
 ### Group icons
 
 ```ts
-// Change icon
-await im.groups.setIcon(chatGuid, attachmentGuid);
+// Get icon
+const iconBytes = await im.groups.getIcon(chatGuid);
+// iconBytes: Uint8Array | null
+
+// Change icon (pass raw image bytes)
+await im.groups.setIcon(chatGuid, imageBytes);  // imageBytes: Uint8Array
 
 // Remove icon
 await im.groups.removeIcon(chatGuid);
@@ -136,7 +153,15 @@ await im.groups.removeIcon(chatGuid);
 ### Group backgrounds
 
 ```ts
-await im.groups.setBackground(chatGuid, { imagePath: "/path/to/image.jpg" });
+// Get background
+const bgInfo = await im.groups.getBackground(chatGuid);
+// bgInfo: BackgroundInfo | null
+
+// Set background (pass raw image bytes)
+const bgInfo2 = await im.groups.setBackground(chatGuid, imageBytes);  // imageBytes: Uint8Array
+// bgInfo2: BackgroundInfo { channelGuid?, imageUrl?, backgroundId? }
+
+// Remove background
 await im.groups.removeBackground(chatGuid);
 ```
 

advanced-kits/imessage/error-handling.mdx

@@ -16,6 +16,17 @@ IMessageError
 └── ConnectionError       network or gRPC transport failure
 ```
 
+**gRPC status code mapping**
+
+| gRPC status | SDK error class |
+|---|---|
+| `UNAUTHENTICATED`, `PERMISSION_DENIED` | `AuthenticationError` |
+| `NOT_FOUND` | `NotFoundError` |
+| `RESOURCE_EXHAUSTED` | `RateLimitError` |
+| `INVALID_ARGUMENT`, `FAILED_PRECONDITION` | `ValidationError` |
+| `UNAVAILABLE`, `DEADLINE_EXCEEDED` | `ConnectionError` |
+| All others | `IMessageError` (base class) |
+
 ## Basic usage
 
 ```ts
@@ -57,13 +68,35 @@ All error subclasses inherit:
 
 ```ts
 class IMessageError extends Error {
-  readonly code: ErrorCode;      // SDK-level error code enum
-  readonly retryable: boolean;   // whether retrying the request may succeed
-  readonly grpcCode: number;     // underlying gRPC status code
+  readonly code: ErrorCode;                    // SDK-level error code enum
+  readonly retryable: boolean;                 // whether retrying the request may succeed
+  readonly grpcCode: number;                   // underlying gRPC status code
+  readonly context: Record<string, string>;    // extra debug info from gRPC trailing metadata
 }
 ```
 
-`retryable` is `true` for `RateLimitError` and `ConnectionError`, `false` for all others.
+The `retryable` flag is read from the server's gRPC trailing metadata (`x-retryable` header), so it is determined by the server on a per-response basis. By convention, `RateLimitError` and `ConnectionError` are typically retryable, but the server may override this for any error type.
+
+## Error codes
+
+`ErrorCode` has 22 values across 6 categories:
+
+| Category | Error codes |
+|---|---|
+| Authentication | `unauthenticated`, `tokenExpired`, `tokenBlocked`, `unauthorized` |
+| Rate limiting | `dailyLimitExceeded`, `recipientLimitExceeded` |
+| Deduplication | `duplicateMessage` |
+| Not found | `chatNotFound`, `messageNotFound`, `attachmentNotFound`, `addressNotFound`, `scheduledMessageNotFound`, `pollNotFound` |
+| Validation | `invalidArgument`, `preconditionFailed`, `operationNotSupported`, `privateApiUnavailable` |
+| Infrastructure | `serviceUnavailable`, `timeout`, `internalError`, `databaseError`, `networkError` |
+
+```ts
+import { ErrorCode } from "@photon-ai/advanced-imessage";
+
+if (err instanceof IMessageError && err.code === ErrorCode.chatNotFound) {
+  // handle specifically
+}
+```
 
 ## Retrying with the SDK
 
@@ -75,8 +108,8 @@ const im = createClient({
   token: "...",
   retry: {
     maxAttempts: 3,
-    initialDelayMs: 200,
-    maxDelayMs: 2000,
+    initialDelay: 200,
+    maxDelay: 5000,
   },
 });
 ```
@@ -85,14 +118,14 @@ When `retry` is enabled, `ConnectionError` and `RateLimitError` are retried tran
 
 ## Escape hatch: `_raw`
 
-If the error exposes insufficient detail, every domain type (including errors) carries `_raw` - the raw gRPC response - for debugging:
+Most domain types carry `_raw` containing the raw gRPC response for debugging purposes. The types that include `_raw` are `Chat`, `Message`, `AttachmentInfo`, and `AddressInfo`. Other types such as `ScheduledMessage`, `FindMyFriend`, and `PollInfo` do not include `_raw`.
 
 ```ts
 try {
   await im.messages.send(chat, "Hello!");
 } catch (err) {
   if (err instanceof IMessageError) {
-    console.log(err.code, err.grpcCode, err.retryable);
+    console.log(err.code, err.grpcCode, err.retryable, err.context);
   }
 }
 ```

advanced-kits/imessage/getting-started.mdx

@@ -52,7 +52,7 @@ const im = createClient(options: ClientOptions): AdvancedIMessage;
 
 | Option | Type | Description |
 |---|---|---|
-| `address` | `string` | Host and port of the Photon server |
+| `address` | `string` | Host (and optional port) of the Photon server |
 | `token` | `string \| () => Promise<string>` | Static token or async token factory |
 | `tls` | `boolean` | Enable TLS (default: `false`) |
 | `timeout` | `number` | Request timeout in milliseconds |