UNPKG

14.1 kBTypeScriptView Raw
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 */
18import { App } from '../app';
19import { BatchResponse, Message, MessagingTopicManagementResponse, MulticastMessage, MessagingDevicesResponse, MessagingDeviceGroupResponse, MessagingPayload, MessagingOptions, MessagingTopicResponse, MessagingConditionResponse } from './messaging-api';
20/**
21 * Messaging service bound to the provided app.
22 */
23export 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}