Merge pull request #670 from Telegram-Mini-Apps/feature/download-file-and-copy-to-clipboard

Feature/download file and copy to clipboard

Author: heyqbnk

.changeset/hip-balloons-bathe.md

@@ -0,0 +1,5 @@
+---
+"@telegram-apps/sdk": minor
+---
+
+Implement `copyTextToClipboard` and `downloadFile`.

apps/docs/packages/telegram-apps-sdk/3-x/utils/uncategorized.md

@@ -1,5 +1,43 @@
 # Uncategorized
 
+## `copyTextToClipboard`
+
+Copies specified text to the clipboard using all known methods.
+
+```ts
+import { copyTextToClipboard } from '@telegram-apps/sdk';
+
+await copyTextToClipboard('My text goes here');
+```
+
+## `downloadFile`
+
+To request file download, use the `downloadFile` function. It accepts a file URL and its proposed saved name.
+
+::: code-group
+
+```ts [Using isAvailable]
+import { downloadFile } from '@telegram-apps/sdk';
+
+if (downloadFile.isAvailable()) {
+  await downloadFile(
+    'https://telegram.org/js/telegram-web-app.js',
+    'telegram-sdk.js',
+  );
+}
+```
+
+```ts [Using ifAvailable]
+import { downloadFile } from '@telegram-apps/sdk';
+
+await downloadFile.ifAvailable(
+  'https://telegram.org/js/telegram-web-app.js',
+  'telegram-sdk.js',
+);
+```
+
+:::
+
 ## `getCurrentTime`
 
 To retrieve the current Telegram server time, use the `getCurrentTime` function. It returns

apps/docs/platform/events.md

@@ -290,9 +290,9 @@ Custom emoji status set.
 
 Available since: **v8.0**
 
-| Field  | Type     | Description                                                      |
-|--------|----------|------------------------------------------------------------------|
-| status | `string` | Request status. Set to `downloading` if the is being downloaded. |
+| Field  | Type     | Description                                                     |
+|--------|----------|-----------------------------------------------------------------|
+| status | `string` | Request status. Set to `downloading` if a file is being loaded. |
 
 ### `fullscreen_changed`
 

apps/docs/platform/methods.md

@@ -432,6 +432,8 @@ Available since: **v8.0**
 
 Displays a native popup prompting the user to download a file.
 
+In turn, the Telegram client emits the [file_download_requested](./events.md#file_download_requested) event.
+
 | Field     | Type     | Description                                 |
 |-----------|----------|---------------------------------------------|
 | url       | `string` | The HTTPS URL of the file to be downloaded. |

packages/sdk/src/scopes/utilities/uncategorized/copyTextToClipboard.ts

@@ -0,0 +1,34 @@
+function fallback(text: string) {
+  const textArea = document.createElement('textarea');
+  textArea.value = text;
+
+  // Avoid scrolling to bottom
+  textArea.style.top = '0';
+  textArea.style.left = '0';
+  textArea.style.position = 'fixed';
+
+  document.body.appendChild(textArea);
+  textArea.focus();
+  textArea.select();
+
+  try {
+    document.execCommand('copy');
+  } finally {
+    document.body.removeChild(textArea);
+  }
+}
+
+/**
+ * Copies specified text to the clipboard.
+ * @param text - text to copy.
+ */
+export async function copyTextToClipboard(text: string): Promise<void> {
+  try {
+    const { clipboard } = navigator;
+    if (clipboard) {
+      return await clipboard.writeText(text);
+    }
+  } catch {
+  }
+  fallback(text);
+}

packages/sdk/src/scopes/utilities/uncategorized/downloadFile.ts

@@ -0,0 +1,36 @@
+import { request } from '@/globals.js';
+import { wrapSafe } from '@/scopes/wrappers/wrapSafe.js';
+import { AccessDeniedError } from '@/errors.js';
+import type { RequestOptionsNoCapture } from '@/types.js';
+
+const METHOD_NAME = 'web_app_request_file_download';
+
+/**
+ * Displays a native popup prompting the user to download a file.
+ * @param url - the HTTPS URL of the file to be downloaded.
+ * @param file - the suggested name for the downloaded file.
+ * @param options - additional request execution options.
+ * @since Mini Apps v8.0
+ * @throws {FunctionNotAvailableError} The environment is unknown
+ * @throws {FunctionNotAvailableError} The SDK is not initialized
+ * @throws {FunctionNotAvailableError} The function is not supported
+ * @throws {AccessDeniedError} User denied the action
+ * @example
+ * if (downloadFile.isAvailable()) {
+ *   await downloadFile('https://telegram.org/js/telegram-web-app.js', 'telegram-sdk.js');
+ * }
+ */
+export const downloadFile = wrapSafe(
+  'downloadFile',
+  (url: string, fileName: string, options?: RequestOptionsNoCapture) => {
+    return request(
+      METHOD_NAME,
+      'file_download_requested',
+      { ...options, params: { url, file_name: fileName } },
+    ).then(response => {
+      if (response.status !== 'downloading') {
+        throw new AccessDeniedError('User denied the action');
+      }
+    });
+  }, { isSupported: METHOD_NAME },
+);

packages/sdk/src/scopes/utilities/uncategorized/exports.ts

@@ -1,3 +1,5 @@
+export { copyTextToClipboard } from './copyTextToClipboard.js';
+export { downloadFile } from './downloadFile.js';
 export { getCurrentTime } from './getCurrentTime.js';
 export { readTextFromClipboard } from './readTextFromClipboard.js';
 export { sendData } from './sendData.js';