1 | /*! firebase-admin v12.0.0 */
|
2 | /*!
|
3 | * @license
|
4 | * Copyright 2017 Google Inc.
|
5 | *
|
6 | * Licensed under the Apache License, Version 2.0 (the "License");
|
7 | * you may not use this file except in compliance with the License.
|
8 | * You may obtain a copy of the License at
|
9 | *
|
10 | * http://www.apache.org/licenses/LICENSE-2.0
|
11 | *
|
12 | * Unless required by applicable law or agreed to in writing, software
|
13 | * distributed under the License is distributed on an "AS IS" BASIS,
|
14 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
15 | * See the License for the specific language governing permissions and
|
16 | * limitations under the License.
|
17 | */
|
18 | import { App } from '../app';
|
19 | import { BatchResponse, Message, MessagingTopicManagementResponse, MulticastMessage, MessagingDevicesResponse, MessagingDeviceGroupResponse, MessagingPayload, MessagingOptions, MessagingTopicResponse, MessagingConditionResponse } from './messaging-api';
|
20 | /**
|
21 | * Messaging service bound to the provided app.
|
22 | */
|
23 | export declare class Messaging {
|
24 | private urlPath;
|
25 | private readonly appInternal;
|
26 | private readonly messagingRequestHandler;
|
27 | /**
|
28 | * The {@link firebase-admin.app#App} associated with the current `Messaging` service
|
29 | * instance.
|
30 | *
|
31 | * @example
|
32 | * ```javascript
|
33 | * var app = messaging.app;
|
34 | * ```
|
35 | */
|
36 | get app(): App;
|
37 | /**
|
38 | * Sends the given message via FCM.
|
39 | *
|
40 | * @param message - The message payload.
|
41 | * @param dryRun - Whether to send the message in the dry-run
|
42 | * (validation only) mode.
|
43 | * @returns A promise fulfilled with a unique message ID
|
44 | * string after the message has been successfully handed off to the FCM
|
45 | * service for delivery.
|
46 | */
|
47 | send(message: Message, dryRun?: boolean): Promise<string>;
|
48 | /**
|
49 | * Sends each message in the given array via Firebase Cloud Messaging.
|
50 | *
|
51 | * Unlike {@link Messaging.sendAll}, this method makes a single RPC call for each message
|
52 | * in the given array.
|
53 | *
|
54 | * The responses list obtained from the return value corresponds to the order of `messages`.
|
55 | * An error from this method or a `BatchResponse` with all failures indicates a total failure,
|
56 | * meaning that none of the messages in the list could be sent. Partial failures or no
|
57 | * failures are only indicated by a `BatchResponse` return value.
|
58 | *
|
59 | * @param messages - A non-empty array
|
60 | * containing up to 500 messages.
|
61 | * @param dryRun - Whether to send the messages in the dry-run
|
62 | * (validation only) mode.
|
63 | * @returns A Promise fulfilled with an object representing the result of the
|
64 | * send operation.
|
65 | */
|
66 | sendEach(messages: Message[], dryRun?: boolean): Promise<BatchResponse>;
|
67 | /**
|
68 | * Sends the given multicast message to all the FCM registration tokens
|
69 | * specified in it.
|
70 | *
|
71 | * This method uses the {@link Messaging.sendEach} API under the hood to send the given
|
72 | * message to all the target recipients. The responses list obtained from the
|
73 | * return value corresponds to the order of tokens in the `MulticastMessage`.
|
74 | * An error from this method or a `BatchResponse` with all failures indicates a total
|
75 | * failure, meaning that the messages in the list could be sent. Partial failures or
|
76 | * failures are only indicated by a `BatchResponse` return value.
|
77 | *
|
78 | * @param message - A multicast message
|
79 | * containing up to 500 tokens.
|
80 | * @param dryRun - Whether to send the message in the dry-run
|
81 | * (validation only) mode.
|
82 | * @returns A Promise fulfilled with an object representing the result of the
|
83 | * send operation.
|
84 | */
|
85 | sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
|
86 | /**
|
87 | * Sends all the messages in the given array via Firebase Cloud Messaging.
|
88 | * Employs batching to send the entire list as a single RPC call. Compared
|
89 | * to the `send()` method, this method is a significantly more efficient way
|
90 | * to send multiple messages.
|
91 | *
|
92 | * The responses list obtained from the return value
|
93 | * corresponds to the order of tokens in the `MulticastMessage`. An error
|
94 | * from this method indicates a total failure, meaning that none of the messages
|
95 | * in the list could be sent. Partial failures are indicated by a `BatchResponse`
|
96 | * return value.
|
97 | *
|
98 | * @param messages - A non-empty array
|
99 | * containing up to 500 messages.
|
100 | * @param dryRun - Whether to send the messages in the dry-run
|
101 | * (validation only) mode.
|
102 | * @returns A Promise fulfilled with an object representing the result of the
|
103 | * send operation.
|
104 | *
|
105 | * @deprecated Use {@link Messaging.sendEach} instead.
|
106 | */
|
107 | sendAll(messages: Message[], dryRun?: boolean): Promise<BatchResponse>;
|
108 | /**
|
109 | * Sends the given multicast message to all the FCM registration tokens
|
110 | * specified in it.
|
111 | *
|
112 | * This method uses the `sendAll()` API under the hood to send the given
|
113 | * message to all the target recipients. The responses list obtained from the
|
114 | * return value corresponds to the order of tokens in the `MulticastMessage`.
|
115 | * An error from this method indicates a total failure, meaning that the message
|
116 | * was not sent to any of the tokens in the list. Partial failures are indicated
|
117 | * by a `BatchResponse` return value.
|
118 | *
|
119 | * @param message - A multicast message
|
120 | * containing up to 500 tokens.
|
121 | * @param dryRun - Whether to send the message in the dry-run
|
122 | * (validation only) mode.
|
123 | * @returns A Promise fulfilled with an object representing the result of the
|
124 | * send operation.
|
125 | *
|
126 | * @deprecated Use {@link Messaging.sendEachForMulticast} instead.
|
127 | */
|
128 | sendMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
|
129 | /**
|
130 | * Sends an FCM message to a single device corresponding to the provided
|
131 | * registration token.
|
132 | *
|
133 | * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_individual_devices |
|
134 | * Send to individual devices}
|
135 | * for code samples and detailed documentation. Takes either a
|
136 | * `registrationToken` to send to a single device or a
|
137 | * `registrationTokens` parameter containing an array of tokens to send
|
138 | * to multiple devices.
|
139 | *
|
140 | * @param registrationToken - A device registration token or an array of
|
141 | * device registration tokens to which the message should be sent.
|
142 | * @param payload - The message payload.
|
143 | * @param options - Optional options to
|
144 | * alter the message.
|
145 | *
|
146 | * @returns A promise fulfilled with the server's response after the message
|
147 | * has been sent.
|
148 | *
|
149 | * @deprecated Use {@link Messaging.send} instead.
|
150 | */
|
151 | sendToDevice(registrationTokenOrTokens: string | string[], payload: MessagingPayload, options?: MessagingOptions): Promise<MessagingDevicesResponse>;
|
152 | /**
|
153 | * Sends an FCM message to a device group corresponding to the provided
|
154 | * notification key.
|
155 | *
|
156 | * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_device_group |
|
157 | * Send to a device group} for code samples and detailed documentation.
|
158 | *
|
159 | * @param notificationKey - The notification key for the device group to
|
160 | * which to send the message.
|
161 | * @param payload - The message payload.
|
162 | * @param options - Optional options to
|
163 | * alter the message.
|
164 | *
|
165 | * @returns A promise fulfilled with the server's response after the message
|
166 | * has been sent.
|
167 | *
|
168 | * @deprecated Use {@link Messaging.send} instead.
|
169 | */
|
170 | sendToDeviceGroup(notificationKey: string, payload: MessagingPayload, options?: MessagingOptions): Promise<MessagingDeviceGroupResponse>;
|
171 | /**
|
172 | * Sends an FCM message to a topic.
|
173 | *
|
174 | * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_topic |
|
175 | * Send to a topic} for code samples and detailed documentation.
|
176 | *
|
177 | * @param topic - The topic to which to send the message.
|
178 | * @param payload - The message payload.
|
179 | * @param options - Optional options to
|
180 | * alter the message.
|
181 | *
|
182 | * @returns A promise fulfilled with the server's response after the message
|
183 | * has been sent.
|
184 | */
|
185 | sendToTopic(topic: string, payload: MessagingPayload, options?: MessagingOptions): Promise<MessagingTopicResponse>;
|
186 | /**
|
187 | * Sends an FCM message to a condition.
|
188 | *
|
189 | * See {@link https://firebase.google.com/docs/cloud-messaging/admin/legacy-fcm#send_to_a_condition |
|
190 | * Send to a condition}
|
191 | * for code samples and detailed documentation.
|
192 | *
|
193 | * @param condition - The condition determining to which topics to send
|
194 | * the message.
|
195 | * @param payload - The message payload.
|
196 | * @param options - Optional options to
|
197 | * alter the message.
|
198 | *
|
199 | * @returns A promise fulfilled with the server's response after the message
|
200 | * has been sent.
|
201 | */
|
202 | sendToCondition(condition: string, payload: MessagingPayload, options?: MessagingOptions): Promise<MessagingConditionResponse>;
|
203 | /**
|
204 | * Subscribes a device to an FCM topic.
|
205 | *
|
206 | * See {@link https://firebase.google.com/docs/cloud-messaging/manage-topics#suscribe_and_unsubscribe_using_the |
|
207 | * Subscribe to a topic}
|
208 | * for code samples and detailed documentation. Optionally, you can provide an
|
209 | * array of tokens to subscribe multiple devices.
|
210 | *
|
211 | * @param registrationTokens - A token or array of registration tokens
|
212 | * for the devices to subscribe to the topic.
|
213 | * @param topic - The topic to which to subscribe.
|
214 | *
|
215 | * @returns A promise fulfilled with the server's response after the device has been
|
216 | * subscribed to the topic.
|
217 | */
|
218 | subscribeToTopic(registrationTokenOrTokens: string | string[], topic: string): Promise<MessagingTopicManagementResponse>;
|
219 | /**
|
220 | * Unsubscribes a device from an FCM topic.
|
221 | *
|
222 | * See {@link https://firebase.google.com/docs/cloud-messaging/admin/manage-topic-subscriptions#unsubscribe_from_a_topic |
|
223 | * Unsubscribe from a topic}
|
224 | * for code samples and detailed documentation. Optionally, you can provide an
|
225 | * array of tokens to unsubscribe multiple devices.
|
226 | *
|
227 | * @param registrationTokens - A device registration token or an array of
|
228 | * device registration tokens to unsubscribe from the topic.
|
229 | * @param topic - The topic from which to unsubscribe.
|
230 | *
|
231 | * @returns A promise fulfilled with the server's response after the device has been
|
232 | * unsubscribed from the topic.
|
233 | */
|
234 | unsubscribeFromTopic(registrationTokenOrTokens: string | string[], topic: string): Promise<MessagingTopicManagementResponse>;
|
235 | private getUrlPath;
|
236 | /**
|
237 | * Helper method which sends and handles topic subscription management requests.
|
238 | *
|
239 | * @param registrationTokenOrTokens - The registration token or an array of
|
240 | * registration tokens to unsubscribe from the topic.
|
241 | * @param topic - The topic to which to subscribe.
|
242 | * @param methodName - The name of the original method called.
|
243 | * @param path - The endpoint path to use for the request.
|
244 | *
|
245 | * @returns A Promise fulfilled with the parsed server
|
246 | * response.
|
247 | */
|
248 | private sendTopicManagementRequest;
|
249 | /**
|
250 | * Validates the types of the messaging payload and options. If invalid, an error will be thrown.
|
251 | *
|
252 | * @param payload - The messaging payload to validate.
|
253 | * @param options - The messaging options to validate.
|
254 | */
|
255 | private validateMessagingPayloadAndOptionsTypes;
|
256 | /**
|
257 | * Validates the messaging payload. If invalid, an error will be thrown.
|
258 | *
|
259 | * @param payload - The messaging payload to validate.
|
260 | *
|
261 | * @returns A copy of the provided payload with whitelisted properties switched
|
262 | * from camelCase to underscore_case.
|
263 | */
|
264 | private validateMessagingPayload;
|
265 | /**
|
266 | * Validates the messaging options. If invalid, an error will be thrown.
|
267 | *
|
268 | * @param options - The messaging options to validate.
|
269 | *
|
270 | * @returns A copy of the provided options with whitelisted properties switched
|
271 | * from camelCase to underscore_case.
|
272 | */
|
273 | private validateMessagingOptions;
|
274 | /**
|
275 | * Validates the type of the provided registration token(s). If invalid, an error will be thrown.
|
276 | *
|
277 | * @param registrationTokenOrTokens - The registration token(s) to validate.
|
278 | * @param method - The method name to use in error messages.
|
279 | * @param errorInfo - The error info to use if the registration tokens are invalid.
|
280 | */
|
281 | private validateRegistrationTokensType;
|
282 | /**
|
283 | * Validates the provided registration tokens. If invalid, an error will be thrown.
|
284 | *
|
285 | * @param registrationTokenOrTokens - The registration token or an array of
|
286 | * registration tokens to validate.
|
287 | * @param method - The method name to use in error messages.
|
288 | * @param errorInfo - The error info to use if the registration tokens are invalid.
|
289 | */
|
290 | private validateRegistrationTokens;
|
291 | /**
|
292 | * Validates the type of the provided topic. If invalid, an error will be thrown.
|
293 | *
|
294 | * @param topic - The topic to validate.
|
295 | * @param method - The method name to use in error messages.
|
296 | * @param errorInfo - The error info to use if the topic is invalid.
|
297 | */
|
298 | private validateTopicType;
|
299 | /**
|
300 | * Validates the provided topic. If invalid, an error will be thrown.
|
301 | *
|
302 | * @param topic - The topic to validate.
|
303 | * @param method - The method name to use in error messages.
|
304 | * @param errorInfo - The error info to use if the topic is invalid.
|
305 | */
|
306 | private validateTopic;
|
307 | /**
|
308 | * Normalizes the provided topic name by prepending it with '/topics/', if necessary.
|
309 | *
|
310 | * @param topic - The topic name to normalize.
|
311 | *
|
312 | * @returns The normalized topic name.
|
313 | */
|
314 | private normalizeTopic;
|
315 | }
|