🤖 Merge PR DefinitelyTyped#68896 [@types/telegram-web-app] feat: add …

…detailed comments for requestContact callback types. by @WuChenDi

Co-authored-by: Muthu Kumar <[email protected]>

types/telegram-web-app/index.d.ts

@@ -157,7 +157,7 @@ interface WebApp {
         eventType: "writeAccessRequested",
         eventHandler: (eventData: { status: "allowed" | "cancelled" }) => void,
     ): void;
-    onEvent(eventType: "contactRequested", eventHandler: (eventData: { status: "sent" | "cancelled" }) => void): void;
+    onEvent(eventType: "contactRequested", eventHandler: (eventData: RequestContactResponse) => void): void;
 
     /** A method that deletes a previously set event handler. */
     offEvent(
@@ -176,7 +176,7 @@ interface WebApp {
         eventType: "writeAccessRequested",
         eventHandler: (eventData: { status: "allowed" | "cancelled" }) => void,
     ): void;
-    offEvent(eventType: "contactRequested", eventHandler: (eventData: { status: "sent" | "cancelled" }) => void): void;
+    offEvent(eventType: "contactRequested", eventHandler: (eventData: RequestContactResponse) => void): void;
 
     /**
      * A method used to send data to the bot. When this method is called, a
@@ -278,9 +278,12 @@ interface WebApp {
      * @param callback If an optional callback parameter was passed, the
      * callback function will be called when the popup is closed and the first
      * argument will be a boolean indicating whether the user shared its
-     * phone number.
+     * phone number. The second argument, contingent upon success, will be
+     * an object detailing the shared contact information or a cancellation response.
      */
-    requestContact(callback?: (success: boolean) => void): void;
+    requestContact(
+        callback?: (success: boolean, response: RequestContactResponse) => void,
+    ): void;
     /**
      * A method that informs the Telegram app that the Web App is ready to be
      * displayed. It is recommended to call this method as early as possible, as
@@ -809,3 +812,43 @@ interface ScanQrPopupParams {
      */
     text?: string;
 }
+
+/**
+ * This object describes contact information shared when requestContact was approved by the user.
+ */
+interface RequestContactResponseSent {
+    /** Status 'sent' indicates that contact information has been shared. */
+    status: "sent";
+    /** A status message or result as a string. */
+    response: string;
+    /** Contains sensitive information shared upon user consent. WARNING: Data from
+     * this field should not be trusted. You should only use data from `response` on
+     * the bot's server and only after it has been validated. */
+    responseUnsafe: {
+        /** Authorization date for sharing contact information. */
+        auth_date: string;
+        /** Object holding user's contact details. */
+        contact: {
+            /** User's first name. */
+            first_name: string;
+            /** Optional. User's last name. */
+            last_name?: string;
+            /** User's phone number. */
+            phone_number: string;
+            /** Unique identifier of the user. */
+            user_id: number;
+        };
+        /** Hash to verify data authenticity. */
+        hash: string;
+    };
+}
+
+/**
+ * This object only contains a status to indicate the cancellation.
+ */
+interface RequestContactResponseCancelled {
+    /** Status 'cancelled', indicates that user cancelled the contact share request. */
+    status: "cancelled";
+}
+
+type RequestContactResponse = RequestContactResponseSent | RequestContactResponseCancelled;

types/telegram-web-app/package.json

@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "@types/telegram-web-app",
-    "version": "7.0.9999",
+    "version": "7.1.9999",
     "nonNpm": "conflict",
     "nonNpmDescription": "telegram-web-app",
     "projects": [

types/telegram-web-app/telegram-web-app-tests.ts

@@ -71,3 +71,25 @@ app.requestWriteAccess(success => {
 app.onEvent("writeAccessRequested", ({ status }) => {});
 
 app.SettingsButton.show();
+
+app.requestContact((success, req) => {
+    if (req.status === "sent") {
+        // no error
+        req.response;
+    } else {
+        // @ts-expect-error
+        req.response;
+        req.status; // $ExpectType "cancelled"
+    }
+});
+
+app.onEvent("contactRequested", (req) => {
+    if (req.status === "sent") {
+        // no error
+        req.response;
+    } else {
+        // @ts-expect-error
+        req.response;
+        req.status; // $ExpectType "cancelled"
+    }
+});