Merge pull request #10 from photon-hq/refactor/api

feat: support poll

Author: Artist-MOBAI

client.ts

@@ -11,6 +11,7 @@ import {
     HandleModule,
     ICloudModule,
     MessageModule,
+    PollModule,
     ScheduledMessageModule,
     ServerModule,
 } from "./modules";
@@ -47,6 +48,7 @@ export class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitt
     public readonly facetime: FaceTimeModule;
     public readonly icloud: ICloudModule;
 
+    public readonly polls: PollModule;
     public readonly scheduledMessages: ScheduledMessageModule;
     public readonly server: ServerModule;
 
@@ -63,6 +65,12 @@ export class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitt
     // a single user/SDK instance are sent in strict order, preventing race conditions.
     private sendQueue: Promise<unknown> = Promise.resolve();
 
+    // Flag to track if 'ready' event has been emitted
+    //
+    // Purpose: Prevent duplicate 'ready' events when both legacy mode (no API key)
+    // and auth-ok events occur, which would cause user callbacks to fire twice.
+    private readyEmitted = false;
+
     private constructor(config: ClientConfig = {}) {
         super();
 
@@ -114,6 +122,7 @@ export class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitt
         this.facetime = new FaceTimeModule(this.http);
         this.icloud = new ICloudModule(this.http);
 
+        this.polls = new PollModule(this.http);
         this.scheduledMessages = new ScheduledMessageModule(this.http);
         this.server = new ServerModule(this.http);
     }
@@ -218,13 +227,17 @@ export class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitt
 
         this.socket.on("disconnect", () => {
             this.logger.info("Disconnected from iMessage server");
+            this.readyEmitted = false;
             this.emit("disconnect");
         });
 
         // Listen for authentication success
         this.socket.on("auth-ok", () => {
             this.logger.info("Authentication successful");
-            this.emit("ready");
+            if (!this.readyEmitted) {
+                this.readyEmitted = true;
+                this.emit("ready");
+            }
         });
 
         // Listen for authentication errors
@@ -243,7 +256,10 @@ export class AdvancedIMessageKit extends EventEmitter implements TypedEventEmitt
             // If no apiKey, assume legacy server that doesn't require auth - emit ready immediately
             if (!this.config.apiKey) {
                 this.logger.info("No API key provided, skipping authentication (legacy server mode)");
-                this.emit("ready");
+                if (!this.readyEmitted) {
+                    this.readyEmitted = true;
+                    this.emit("ready");
+                }
             }
         });
 

examples/poll-add-option.ts

@@ -0,0 +1,45 @@
+import { createSDK, handleError } from "./utils";
+
+const CHAT_GUID = process.env.CHAT_GUID || "any;-;+1234567890";
+
+async function main() {
+    const sdk = createSDK();
+
+    sdk.on("ready", async () => {
+        console.log("Poll creation and add option example...\n");
+
+        try {
+            console.log("Step 1: Creating a poll with 2 options...");
+            const pollMessage = await sdk.polls.create({
+                chatGuid: CHAT_GUID,
+                title: "",
+                options: ["Option A", "Option B"],
+            });
+
+            console.log("✓ Poll created!");
+            console.log(`Poll GUID: ${pollMessage.guid}`);
+
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+
+            console.log("\nStep 2: Adding a new option...");
+            const editMessage = await sdk.polls.addOption({
+                chatGuid: CHAT_GUID,
+                pollMessageGuid: pollMessage.guid,
+                optionText: "Option C - Added Later",
+            });
+
+            console.log("✓ Option added!");
+            console.log(`Edit message GUID: ${editMessage.guid}`);
+            console.log(`Associated Message Type: ${editMessage.associatedMessageType}`);
+        } catch (error) {
+            handleError(error, "Poll operation failed");
+        }
+
+        await sdk.close();
+        process.exit(0);
+    });
+
+    await sdk.connect();
+}
+
+main().catch(console.error);

examples/poll-create.ts

@@ -0,0 +1,42 @@
+import { createSDK, handleError } from "./utils";
+
+const CHAT_GUID = process.env.CHAT_GUID || "any;-;+1234567890";
+
+async function main() {
+    const sdk = createSDK();
+
+    sdk.on("ready", async () => {
+        console.log("Poll creation example...\n");
+
+        try {
+            console.log("Creating a poll...");
+            const pollMessage = await sdk.polls.create({
+                chatGuid: CHAT_GUID,
+                title: "",
+                options: [
+                    "Option A - First choice",
+                    "Option B - Second choice",
+                    "Option C - Third choice",
+                    "Option D - Fourth choice",
+                ],
+            });
+
+            console.log("\n✓ Poll created successfully!");
+            console.log(`Poll message GUID: ${pollMessage.guid}`);
+            console.log(`Balloon Bundle ID: ${pollMessage.balloonBundleId}`);
+
+            if (pollMessage.payloadData) {
+                console.log(`\nPayload Data: ${JSON.stringify(pollMessage.payloadData, null, 2)}`);
+            }
+        } catch (error) {
+            handleError(error, "Failed to create poll");
+        }
+
+        await sdk.close();
+        process.exit(0);
+    });
+
+    await sdk.connect();
+}
+
+main().catch(console.error);

examples/test.txt

@@ -0,0 +1 @@
+123456

modules/index.ts

@@ -5,5 +5,6 @@ export * from "./facetime";
 export * from "./handle";
 export * from "./icloud";
 export * from "./message";
+export * from "./poll";
 export * from "./scheduled";
 export * from "./server";

modules/poll.ts

@@ -0,0 +1,54 @@
+import type { AxiosInstance } from "axios";
+import type { AddPollOptionOptions, CreatePollOptions, PollMessageResponse, VotePollOptions } from "../types/poll";
+
+export class PollModule {
+    constructor(private readonly http: AxiosInstance) {}
+
+    async create(options: CreatePollOptions): Promise<PollMessageResponse> {
+        if (options.options.length < 2) {
+            throw new Error("Poll must have at least 2 options");
+        }
+
+        const { data } = await this.http.post("/api/v1/poll/create", {
+            chatGuid: options.chatGuid,
+            title: options.title ?? "",
+            options: options.options,
+        });
+
+        return data.data;
+    }
+
+    async vote(options: VotePollOptions): Promise<PollMessageResponse> {
+        const { data } = await this.http.post("/api/v1/poll/vote", {
+            chatGuid: options.chatGuid,
+            pollMessageGuid: options.pollMessageGuid,
+            optionIdentifier: options.optionIdentifier,
+        });
+
+        return data.data;
+    }
+
+    async unvote(options: VotePollOptions): Promise<PollMessageResponse> {
+        const { data } = await this.http.post("/api/v1/poll/unvote", {
+            chatGuid: options.chatGuid,
+            pollMessageGuid: options.pollMessageGuid,
+            optionIdentifier: options.optionIdentifier,
+        });
+
+        return data.data;
+    }
+
+    async addOption(options: AddPollOptionOptions): Promise<PollMessageResponse> {
+        if (!options.optionText || options.optionText.trim().length === 0) {
+            throw new Error("Option text cannot be empty");
+        }
+
+        const { data } = await this.http.post("/api/v1/poll/option", {
+            chatGuid: options.chatGuid,
+            pollMessageGuid: options.pollMessageGuid,
+            optionText: options.optionText,
+        });
+
+        return data.data;
+    }
+}

types/index.ts

@@ -6,6 +6,7 @@ export * from "./facetime";
 export * from "./findmy";
 export * from "./handle";
 export * from "./message";
+export * from "./poll";
 export * from "./scheduled";
 export * from "./server";
 export * from "./sticker";

types/poll.ts

@@ -0,0 +1,51 @@
+import type { MessageResponse } from "./message";
+
+export interface CreatePollOptions {
+    chatGuid: string;
+    title?: string;
+    options: string[];
+}
+
+export interface VotePollOptions {
+    chatGuid: string;
+    pollMessageGuid: string;
+    optionIdentifier: string;
+}
+
+export interface AddPollOptionOptions {
+    chatGuid: string;
+    pollMessageGuid: string;
+    optionText: string;
+}
+
+export interface PollOption {
+    optionIdentifier: string;
+    text: string;
+    attributedText: string;
+    creatorHandle: string;
+    canBeEdited: boolean;
+}
+
+export interface PollVote {
+    voteOptionIdentifier: string;
+    participantHandle: string;
+    serverVoteTime?: number;
+}
+
+export interface PollDefinition {
+    version: number;
+    item: {
+        title: string;
+        orderedPollOptions: PollOption[];
+        creatorHandle: string;
+    };
+}
+
+export interface PollVoteResponse {
+    version: number;
+    item: {
+        votes: PollVote[];
+    };
+}
+
+export type PollMessageResponse = MessageResponse;