@telegram.ts/types 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telegram.ts/types",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Comprehensive Type Declarations for Telegram Bot API with telegramsjs",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",

package/src/apiMethodsTypes.d.ts

@@ -190,7 +190,7 @@ export type ApiMethods = {
     protect_content?: boolean;
   }): MessageId[];
 
-  /** Use this method to copy messages of any kind. Service messages, giveaway messages, giveaway winners messages, and invoice messages can't be copied. A quiz poll can be copied only if the value of the field correct_option_id is known to the bot. The method is analogous to the method forwardMessage, but the copied message doesn't have a link to the original message. Returns the MessageId of the sent message on success. */
+  /** Use this method to copy messages of any kind. Service messages, paid media messages, giveaway messages, giveaway winners messages, and invoice messages can't be copied. A quiz poll can be copied only if the value of the field correct_option_id is known to the bot. The method is analogous to the method forwardMessage, but the copied message doesn't have a link to the original message. Returns the MessageId of the sent message on success. */
   copyMessage(args: {
     /** Unique identifier for the target chat or username of the target channel (in the format @channelusername) */
     chat_id: number | string;
@@ -224,7 +224,7 @@ export type ApiMethods = {
     reply_to_message_id?: number;
   }): MessageId;
 
-  /** Use this method to copy messages of any kind. If some of the specified messages can't be found or copied, they are skipped. Service messages, giveaway messages, giveaway winners messages, and invoice messages can't be copied. A quiz poll can be copied only if the value of the field correct_option_id is known to the bot. The method is analogous to the method forwardMessages, but the copied messages don't have a link to the original message. Album grouping is kept for copied messages. On success, an array of MessageId of the sent messages is returned. */
+  /** Use this method to copy messages of any kind. If some of the specified messages can't be found or copied, they are skipped. Service messages, paid media messages, giveaway messages, giveaway winners messages,  and invoice messages can't be copied. A quiz poll can be copied only if the value of the field correct_option_id is known to the bot. The method is analogous to the method forwardMessages, but the copied messages don't have a link to the original message. Album grouping is kept for copied messages. On success, an array of MessageId of the sent messages is returned. */
   copyMessages(args: {
     /** Unique identifier for the target chat or username of the target channel (in the format @channelusername) */
     chat_id: number | string;
@@ -634,6 +634,36 @@ export type ApiMethods = {
     reply_markup?: InlineKeyboardMarkup;
   }): (Update.Edited & Message.LocationMessage) | true;
 
+  /** Use this method to send paid media to channel chats. On success, the sent Message is returned. */
+  sendPaidMedia(args: {
+    /** Unique identifier for the target chat or username of the target channel (in the format @channelusername) */
+    chat_id: number | string;
+    /** The number of Telegram Stars that must be paid to buy access to the media */
+    star_count: number;
+    /** An array describing the media to be sent; up to 10 items */
+    media: InputPaidMedia[];
+    /** Media caption, 0-1024 characters after entities parsing */
+    caption?: string;
+    /** Mode for parsing entities in the media caption. See formatting options for more details. */
+    parse_mode?: string;
+    /** A list of special entities that appear in the caption, which can be specified instead of parse_mode */
+    caption_entities?: MessageEntity[];
+    /** Pass True, if the caption must be shown above the message media */
+    show_caption_above_media?: boolean;
+    /** Sends the message silently. Users will receive a notification with no sound. */
+    disable_notification?: boolean;
+    /** Protects the contents of the sent message from forwarding and saving */
+    protect_content?: boolean;
+    /** Description of the message to reply to */
+    reply_parameters?: ReplyParameters;
+    /** Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user */
+    reply_markup?:
+      | InlineKeyboardMarkup
+      | ReplyKeyboardMarkup
+      | ReplyKeyboardRemove
+      | ForceReply;
+  }): Message.PaidMediaMessage;
+
   /** Use this method to send information about a venue. On success, the sent Message is returned. */
   sendVenue(args: {
     /** Unique identifier of the business connection on behalf of which the message will be sent */
@@ -2008,3 +2038,34 @@ export interface InputMediaDocument {
   /** Disables automatic server-side content type detection for files uploaded using multipart/form-data. Always true, if the document is sent as part of an album. */
   disable_content_type_detection?: boolean;
 }
+
+/** This object describes the paid media to be sent. Currently, it can be one of
+- InputPaidMediaPhoto
+- InputPaidMediaVideo */
+export type InputPaidMedia = InputMediaPhoto | InputPaidMediaVideo;
+
+/** The paid media to send is a photo. */
+export interface InputPaidMediaPhoto {
+  /** Type of the media, must be photo */
+  type: "photo";
+  /** File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files » */
+  media: Buffer | ReadStream | string;
+}
+
+/** The paid media to send is a video. */
+export interface InputPaidMediaVideo {
+  /** Type of the media, must be video */
+  type: "video";
+  /** File to send. Pass a file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet, or pass “attach://<file_attach_name>” to upload a new one using multipart/form-data under <file_attach_name> name. More information on Sending Files » */
+  media: Buffer | ReadStream | string;
+  /** Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://<file_attach_name>” if the thumbnail was uploaded using multipart/form-data under <file_attach_name>. More information on Sending Files » */
+  thumbnail?: Buffer | ReadStream | string;
+  /** Video width */
+  width?: number;
+  /** Video height */
+  height?: number;
+  /** Video duration in seconds */
+  duration?: number;
+  /** Pass True if the uploaded video is suitable for streaming */
+  supports_streaming?: boolean;
+}

package/src/botCommandTypes.d.ts

@@ -56,10 +56,7 @@ export interface MenuButtonWebApp {
   type: "web_app";
   /** The text on the button. */
   text: string;
-  /**
-   * The description of the Web App that will be launched when the user presses the button.
-   * The Web App will be able to send an arbitrary message on behalf of the user using the method answerWebAppQuery.
-   */
+  /** Description of the Web App that will be launched when the user presses the button. The Web App will be able to send an arbitrary message on behalf of the user using the method answerWebAppQuery. Alternatively, a t.me link to a Web App can be specified in the object instead of the Web App's URL, in which case the Web App will be opened as if the user pressed the link. */
   web_app: WebAppInfo;
 }
 

package/src/invoiceTypes.d.ts

@@ -1,150 +1,129 @@
 import type { User } from "./manageTypes";
 
-/**
- * This interface represents a labeled portion of the price for goods or services.
- */
+/** This object represents a portion of the price for goods or services. */
 export interface LabeledPrice {
-  /** The label of the portion. */
+  /** Portion label */
   label: string;
-  /**
-   * The price of the product in the smallest units of the currency (integer, not float/double).
-   * For example, for a price of US$ 1.45, the amount would be 145.
-   * See the 'exp' parameter in currencies.json for the number of digits past the decimal point for each currency
-   * (2 for the majority of currencies).
-   */
+  /** Price of the product in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
   amount: number;
 }
 
-/**
- * This interface contains basic information about an invoice.
- */
+/** This object contains basic information about an invoice. */
 export interface Invoice {
-  /** The name of the product. */
+  /** Product name */
   title: string;
-  /** The description of the product. */
+  /** Product description */
   description: string;
-  /** A unique bot deep-linking parameter that can be used to generate this invoice. */
+  /** Unique bot deep-linking parameter that can be used to generate this invoice */
   start_parameter: string;
-  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars. */
+  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
   currency: string;
-  /**
-   * The total price in the smallest units of the currency (integer, not float/double).
-   * For example, for a price of US$ 1.45, the total_amount would be 145.
-   * See the 'exp' parameter in currencies.json for the number of digits past the decimal point for each currency
-   * (2 for the majority of currencies).
-   */
+  /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
   total_amount: number;
 }
 
-/**
- * This interface represents a shipping address.
- */
+/** This object represents a shipping address. */
 export interface ShippingAddress {
-  /** The two-letter ISO 3166-1 alpha-2 country code. */
+  /** Two-letter ISO 3166-1 alpha-2 country code */
   country_code: string;
-  /** The state, if applicable. */
+  /** State, if applicable */
   state: string;
-  /** The city. */
+  /** City */
   city: string;
-  /** The first line for the address. */
+  /** First line for the address */
   street_line1: string;
-  /** The second line for the address. */
+  /** Second line for the address */
   street_line2: string;
-  /** The address postal code. */
+  /** Address post code */
   post_code: string;
 }
 
-/**
- * This interface represents information about an order.
- */
+/** This object represents information about an order. */
 export interface OrderInfo {
-  /** The user's name. */
+  /** User name */
   name?: string;
-  /** The user's phone number. */
+  /** User's phone number */
   phone_number?: string;
-  /** The user's email. */
+  /** User email */
   email?: string;
-  /** The user's shipping address. */
+  /** User shipping address */
   shipping_address?: ShippingAddress;
 }
 
-/**
- * This interface represents a shipping option.
- */
+/** This object represents one shipping option. */
 export interface ShippingOption {
-  /** The shipping option identifier. */
+  /** Shipping option identifier */
   id: string;
-  /** The title of the option. */
+  /** Option title */
   title: string;
-  /** The list of price portions. */
+  /** List of price portions */
   prices: LabeledPrice[];
 }
 
-/**
- * This interface contains basic information about a successful payment.
- */
+/** This object contains basic information about a successful payment. */
 export interface SuccessfulPayment {
-  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars. */
+  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
   currency: string;
-  /**
-   * The total price in the smallest units of the currency (integer, not float/double).
-   * For example, for a price of US$ 1.45, the total_amount would be 145.
-   * See the 'exp' parameter in currencies.json for the number of digits past the decimal point for each currency
-   * (2 for the majority of currencies).
-   */
+  /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
   total_amount: number;
-  /** The bot-specified invoice payload. */
+  /** Bot specified invoice payload */
   invoice_payload: string;
-  /** The identifier of the shipping option chosen by the user. */
+  /** Identifier of the shipping option chosen by the user */
   shipping_option_id?: string;
-  /** The order information provided by the user. */
+  /** Order information provided by the user */
   order_info?: OrderInfo;
-  /** The Telegram payment identifier. */
+  /** Telegram payment identifier */
   telegram_payment_charge_id: string;
-  /** The provider payment identifier. */
+  /** Provider payment identifier */
   provider_payment_charge_id: string;
 }
 
-/**
- * This interface contains information about an incoming shipping query.
- */
+/** This object contains basic information about a refunded payment. */
+export interface RefundedPayment {
+  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars. Currently, always “XTR” */
+  currency: string;
+  /** Total refunded price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45, total_amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
+  total_amount: number;
+  /** Bot-specified invoice payload */
+  invoice_payload: string;
+  /** Telegram payment identifier */
+  telegram_payment_charge_id: string;
+  /** Provider payment identifier */
+  provider_payment_charge_id?: string;
+}
+
+/** This object contains information about an incoming shipping query. */
 export interface ShippingQuery {
-  /** The unique query identifier. */
+  /** Unique query identifier */
   id: string;
-  /** The user who sent the query. */
+  /** User who sent the query */
   from: User;
-  /** The bot-specified invoice payload. */
+  /** Bot specified invoice payload */
   invoice_payload: string;
-  /** The user-specified shipping address. */
+  /** User specified shipping address */
   shipping_address: ShippingAddress;
 }
 
-/**
- * This interface contains information about an incoming pre-checkout query.
- */
+/** This object contains information about an incoming pre-checkout query. */
 export interface PreCheckoutQuery {
-  /** The unique query identifier. */
+  /** Unique query identifier */
   id: string;
-  /** The user who sent the query. */
+  /** User who sent the query */
   from: User;
-  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars. */
+  /** Three-letter ISO 4217 currency code, or “XTR” for payments in Telegram Stars */
   currency: string;
-  /**
-   * The total price in the smallest units of the currency (integer, not float/double).
-   * For example, for a price of US$ 1.45, the total_amount would be 145.
-   * See the 'exp' parameter in currencies.json for the number of digits past the decimal point for each currency
-   * (2 for the majority of currencies).
-   */
+  /** Total price in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). */
   total_amount: number;
-  /** The bot-specified invoice payload. */
+  /** Bot specified invoice payload */
   invoice_payload: string;
-  /** The identifier of the shipping option chosen by the user. */
+  /** Identifier of the shipping option chosen by the user */
   shipping_option_id?: string;
-  /** The order information provided by the user. */
+  /** Order information provided by the user */
   order_info?: OrderInfo;
 }
 
 /** This object describes the state of a revenue withdrawal operation. Currently, it can be one of
+
 - RevenueWithdrawalStatePending
 - RevenueWithdrawalStateSucceeded
 - RevenueWithdrawalStateFailed */
@@ -176,14 +155,27 @@ export interface RevenueWithdrawalStateFailed {
 }
 
 /** This object describes the source of a transaction, or its recipient for outgoing transactions. Currently, it can be one of
-- TransactionPartnerFragment
+
 - TransactionPartnerUser
+- TransactionPartnerFragment
+- TransactionPartnerTelegramAds
 - TransactionPartnerOther */
 export type TransactionPartner =
-  | TransactionPartnerFragment
   | TransactionPartnerUser
+  | TransactionPartnerFragment
+  | TransactionPartnerTelegramAds
   | TransactionPartnerOther;
 
+/** Describes a transaction with a user. */
+export interface TransactionPartnerUser {
+  /** Type of the transaction partner, always “user” */
+  type: "user";
+  /** Information about the user */
+  user: User;
+  /** Bot-specified invoice payload */
+  invoice_payload?: string;
+}
+
 /** Describes a withdrawal transaction with Fragment. */
 export interface TransactionPartnerFragment {
   /** Type of the transaction partner, always “fragment” */
@@ -192,12 +184,10 @@ export interface TransactionPartnerFragment {
   withdrawal_state?: RevenueWithdrawalState;
 }
 
-/** Describes a transaction with a user. */
-export interface TransactionPartnerUser {
-  /** Type of the transaction partner, always “user” */
-  type: "user";
-  /** Information about the user */
-  user: User;
+/** Describes a withdrawal transaction to the Telegram Ads platform. */
+export interface TransactionPartnerTelegramAds {
+  /** Type of the transaction partner, always “telegram_ads” */
+  type: "telegram_ads";
 }
 
 /** Describes a transaction with an unknown source or recipient. */

package/src/manageTypes.d.ts

@@ -230,6 +230,8 @@ export declare namespace ChatFullInfo {
     linked_chat_id?: undefined;
     /** For supergroups, the location to which the supergroup is connected */
     location?: undefined;
+    /** True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats. */
+    can_send_paid_media?: undefined;
   }
   /** Internal type for group chats */
   export interface GroupChat {
@@ -319,6 +321,8 @@ export declare namespace ChatFullInfo {
     linked_chat_id?: undefined;
     /** For supergroups, the location to which the supergroup is connected */
     location?: undefined;
+    /** True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats. */
+    can_send_paid_media?: undefined;
   }
   /** Internal type for supergroup chats */
   export interface SupergroupChat {
@@ -408,6 +412,8 @@ export declare namespace ChatFullInfo {
     linked_chat_id?: number;
     /** For supergroups, the location to which the supergroup is connected */
     location?: ChatLocation;
+    /** True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats. */
+    can_send_paid_media?: undefined;
   }
   /** Internal type for channel chats */
   export interface ChannelChat {
@@ -497,6 +503,8 @@ export declare namespace ChatFullInfo {
     linked_chat_id?: number;
     /** For supergroups, the location to which the supergroup is connected */
     location?: undefined;
+    /** True, if paid media messages can be sent or forwarded to the channel chat. The field is available only for channel chats. */
+    can_send_paid_media?: undefined;
   }
 }
 

package/src/messageTypes.d.ts

@@ -88,6 +88,7 @@ export declare namespace Message {
   export type GameMessage = CommonMessage & MsgWith<"game">;
   export type PollMessage = CommonMessage & MsgWith<"poll">;
   export type LocationMessage = CommonMessage & MsgWith<"location">;
+  export type PaidMediaMessage = CommonMessage & MsgWith<"paid_media">;
   export type VenueMessage = LocationMessage & MsgWith<"venue">;
   export type NewChatMembersMessage = ServiceMessage &
     MsgWith<"new_chat_members">;
@@ -113,6 +114,8 @@ export declare namespace Message {
   export type InvoiceMessage = ServiceMessage & MsgWith<"invoice">;
   export type SuccessfulPaymentMessage = ServiceMessage &
     MsgWith<"successful_payment">;
+  export type RefundedPaymentMessage = ServiceMessage &
+    MsgWith<"refunded_payment">;
   export type UsersSharedMessage = ServiceMessage & MsgWith<"users_shared">;
   export type ChatSharedMessage = ServiceMessage & MsgWith<"chat_shared">;
   export type ConnectedWebsiteMessage = ServiceMessage &
@@ -192,6 +195,8 @@ export interface Message extends Message.MediaMessage {
   venue?: Venue;
   /** Message is a shared location, information about the location */
   location?: Location;
+  /** Message contains paid media; information about the paid media */
+  paid_media?: PaidMediaInfo;
   /** New members that were added to the group or supergroup and information about them (the bot itself may be one of these members) */
   new_chat_members?: User[];
   /** A member was removed from the group, information about them (this member may be the bot itself) */
@@ -220,6 +225,8 @@ export interface Message extends Message.MediaMessage {
   invoice?: Invoice;
   /** Message is a service message about a successful payment, information about the payment. More about payments » */
   successful_payment?: SuccessfulPayment;
+  /** Message is a service message about a refunded payment, information about the payment. More about payments » */
+  refunded_payment?: RefundedPayment;
   /** Service message: users were shared with the bot */
   users_shared?: UsersShared;
   /** Service message: a chat was shared with the bot */
@@ -530,6 +537,8 @@ export interface ExternalReplyInfo {
   invoice?: Invoice;
   /** Message is a shared location, information about the location */
   location?: Location;
+  /** Message contains paid media; information about the paid media */
+  paid_media?: PaidMediaInfo;
   /** Message is a native poll, information about the poll */
   poll?: Poll;
   /** Message is a venue, information about the venue */
@@ -839,6 +848,48 @@ export interface Location {
   proximity_alert_radius?: number;
 }
 
+/** Describes the paid media added to a message. */
+export interface PaidMediaInfo {
+  /** The number of Telegram Stars that must be paid to buy access to the media */
+  star_count: number;
+  /** Information about the paid media */
+  paid_media: PaidMedia[];
+}
+
+/** This object describes paid media. Currently, it can be one of
+- PaidMediaPreview
+- PaidMediaPhoto
+- PaidMediaVideo */
+export type PaidMedia = PaidMediaPreview | PaidMediaPhoto | PaidMediaVideo;
+
+/** The paid media isn't available before the payment. */
+export interface PaidMediaPreview {
+  /** Type of the paid media, always “preview” */
+  type: "preview";
+  /** Media width as defined by the sender */
+  width?: number;
+  /** Media height as defined by the sender */
+  height?: number;
+  /** Duration of the media in seconds as defined by the sender */
+  duration?: number;
+}
+
+/** The paid media is a photo. */
+export interface PaidMediaPhoto {
+  /** Type of the paid media, always “photo” */
+  type: "photo";
+  /** The photo */
+  photo: PhotoSize[];
+}
+
+/** The paid media is a video. */
+export interface PaidMediaVideo {
+  /** Type of the paid media, always “video” */
+  type: "video";
+  /** The video */
+  video: Video;
+}
+
 /** This object represents a venue. */
 export interface Venue {
   /** Venue location. Can't be a live location */