@google-cloud/pubsub 2.17.0 → 2.18.3

package/build/src/subscription.d.ts

@@ -123,7 +123,8 @@ export declare type DetachSubscriptionResponse = EmptyResponse;
  * @param {string} name The name of the subscription.
  * @param {SubscriberOptions} [options] Options for handling messages.
  *
- * @example <caption>From {@link PubSub#getSubscriptions}</caption>
+ * @example From {@link PubSub#getSubscriptions}
+ * ```
  * const {PubSub} = require('@google-cloud/pubsub');
  * const pubsub = new PubSub();
  *
@@ -131,26 +132,32 @@ export declare type DetachSubscriptionResponse = EmptyResponse;
  *   // `subscriptions` is an array of Subscription objects.
  * });
  *
- * @example <caption>From {@link Topic#getSubscriptions}</caption>
+ * ```
+ * @example From {@link Topic#getSubscriptions}
+ * ```
  * const topic = pubsub.topic('my-topic');
  * topic.getSubscriptions((err, subscriptions) => {
  *   // `subscriptions` is an array of Subscription objects.
  * });
  *
- * @example <caption>{@link Topic#createSubscription}</caption>
+ * ```
+ * @example {@link Topic#createSubscription}
+ * ```
  * const topic = pubsub.topic('my-topic');
  * topic.createSubscription('new-subscription', (err, subscription) => {
  *   // `subscription` is a Subscription object.
  * });
  *
- * @example <caption>{@link Topic#subscription}</caption>
+ * ```
+ * @example {@link Topic#subscription}
+ * ```
  * const topic = pubsub.topic('my-topic');
  * const subscription = topic.subscription('my-subscription');
  * // `subscription` is a Subscription object.
  *
- * @example <caption>Once you have obtained a subscription object, you may begin
- * to register listeners. This will automatically trigger pulling for messages.
- * </caption>
+ * ```
+ * @example Once you have obtained a subscription object, you may begin to register listeners. This will automatically trigger pulling for messages.
+ * ```
  * // Register an error handler.
  * subscription.on('error', (err) => {});
  *
@@ -179,8 +186,9 @@ export declare type DetachSubscriptionResponse = EmptyResponse;
  * // Remove the listener from receiving `message` events.
  * subscription.removeListener('message', onMessage);
  *
- * @example <caption>To apply a fine level of flow control, consider the
- * following configuration</caption>
+ * ```
+ * @example To apply a fine level of flow control, consider the following configuration
+ * ```
  * const subscription = topic.subscription('my-sub', {
  *   flowControl: {
  *     maxMessages: 1,
@@ -188,6 +196,7 @@ export declare type DetachSubscriptionResponse = EmptyResponse;
  *     allowExcessMessages: false
  *   }
  * });
+ * ```
  */
 export declare class Subscription extends EventEmitter {
     pubsub: PubSub;
@@ -208,27 +217,367 @@ export declare class Subscription extends EventEmitter {
      * @type {string}
      */
     get projectId(): string;
+    /**
+     * Closes the Subscription, once this is called you will no longer receive
+     * message events unless you call {Subscription#open} or add new message
+     * listeners.
+     *
+     * @param {function} [callback] The callback function.
+     * @param {?error} callback.err An error returned while closing the
+     *     Subscription.
+     *
+     * @example
+     * ```
+     * subscription.close(err => {
+     *   if (err) {
+     *     // Error handling omitted.
+     *   }
+     * });
+     *
+     * // If the callback is omitted a Promise will be returned.
+     * subscription.close().then(() => {});
+     * ```
+     */
     close(): Promise<void>;
     close(callback: SubscriptionCloseCallback): void;
+    /**
+     * Create a subscription.
+     *
+     * @see [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create}
+     *
+     * @throws {Error} If subscription name is omitted.
+     *
+     * @param {string} name The name of the subscription.
+     * @param {CreateSubscriptionRequest} [options] See a
+     *     [Subscription
+     * resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions).
+     * @param {CreateSubscriptionCallback} [callback] Callback function.
+     * @returns {Promise<CreateSubscriptionResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('newMessages');
+     * const callback = function(err, subscription, apiResponse) {};
+     *
+     * subscription.create(callback);
+     *
+     * ```
+     * @example With options
+     * ```
+     * subscription.create({
+     *   ackDeadlineSeconds: 90
+     * }, callback);
+     *
+     * ```
+     * @example If the callback is omitted, we'll return a Promise.
+     * ```
+     * const [sub, apiResponse] = await subscription.create();
+     * ```
+     */
     create(options?: CreateSubscriptionOptions): Promise<CreateSubscriptionResponse>;
     create(callback: CreateSubscriptionCallback): void;
     create(options: CreateSubscriptionOptions, callback: CreateSubscriptionCallback): void;
+    /**
+     * @typedef {array} CreateSnapshotResponse
+     * @property {Snapshot} 0 The new {@link Snapshot}.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback CreateSnapshotCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Snapshot} snapshot The new {@link Snapshot}.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Create a snapshot with the given name.
+     *
+     * @param {string} name Name of the snapshot.
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {CreateSnapshotCallback} [callback] Callback function.
+     * @returns {Promise<CreateSnapshotResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * const callback = (err, snapshot, apiResponse) => {
+     *   if (!err) {
+     *     // The snapshot was created successfully.
+     *   }
+     * };
+     *
+     * subscription.createSnapshot('my-snapshot', callback);
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.createSnapshot('my-snapshot').then((data) => {
+     *   const snapshot = data[0];
+     *   const apiResponse = data[1];
+     * });
+     * ```
+     */
     createSnapshot(name: string, gaxOpts?: CallOptions): Promise<CreateSnapshotResponse>;
     createSnapshot(name: string, callback: CreateSnapshotCallback): void;
     createSnapshot(name: string, gaxOpts: CallOptions, callback: CreateSnapshotCallback): void;
+    /**
+     * Delete the subscription. Pull requests from the current subscription will
+     * be errored once unsubscription is complete.
+     *
+     * @see [Subscriptions: delete API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/delete}
+     *
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {function} [callback] The callback function.
+     * @param {?error} callback.err An error returned while making this
+     *     request.
+     * @param {object} callback.apiResponse Raw API response.
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * subscription.delete((err, apiResponse) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.delete().then((data) => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     delete(gaxOpts?: CallOptions): Promise<EmptyResponse>;
     delete(callback: EmptyCallback): void;
     delete(gaxOpts: CallOptions, callback: EmptyCallback): void;
+    /**
+     * @typedef {array} SubscriptionDetachedResponse
+     * @property {boolean} 0 Whether the subscription is detached.
+     */
+    /**
+     * @callback SubscriptionDetachedCallback
+     * @param {?Error} err Request error, if any.
+     * @param {boolean} exists Whether the subscription is detached.
+     */
+    /**
+     * Check if a subscription is detached.
+     *
+     * @param {SubscriptionDetachedCallback} [callback] Callback function.
+     * @returns {Promise<SubscriptionDetachedResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * subscription.detached((err, exists) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.detached().then((data) => {
+     *   const detached = data[0];
+     * });
+     * ```
+     */
     detached(): Promise<DetachedResponse>;
     detached(callback: DetachedCallback): void;
+    /**
+     * @typedef {array} SubscriptionExistsResponse
+     * @property {boolean} 0 Whether the subscription exists
+     */
+    /**
+     * @callback SubscriptionExistsCallback
+     * @param {?Error} err Request error, if any.
+     * @param {boolean} exists Whether the subscription exists.
+     */
+    /**
+     * Check if a subscription exists.
+     *
+     * @param {SubscriptionExistsCallback} [callback] Callback function.
+     * @returns {Promise<SubscriptionExistsResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * subscription.exists((err, exists) => {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.exists().then((data) => {
+     *   const exists = data[0];
+     * });
+     * ```
+     */
     exists(): Promise<ExistsResponse>;
     exists(callback: ExistsCallback): void;
+    /**
+     * @typedef {array} GetSubscriptionResponse
+     * @property {Subscription} 0 The {@link Subscription}.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetSubscriptionCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Subscription} subscription The {@link Subscription}.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get a subscription if it exists.
+     *
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {boolean} [gaxOpts.autoCreate=false] Automatically create the
+     *     subscription if it does not already exist.
+     * @param {GetSubscriptionCallback} [callback] Callback function.
+     * @returns {Promise<GetSubscriptionResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * subscription.get((err, subscription, apiResponse) => {
+     *   // The `subscription` data has been populated.
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.get().then((data) => {
+     *   const subscription = data[0];
+     *   const apiResponse = data[1];
+     * });
+     * ```
+     */
     get(gaxOpts?: GetSubscriptionOptions): Promise<GetSubscriptionResponse>;
     get(callback: GetSubscriptionCallback): void;
     get(gaxOpts: GetSubscriptionOptions, callback: GetSubscriptionCallback): void;
+    /**
+     * @typedef {array} GetSubscriptionMetadataResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback GetSubscriptionMetadataCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Fetches the subscriptions metadata.
+     *
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {GetSubscriptionMetadataCallback} [callback] Callback function.
+     * @returns {Promise<GetSubscriptionMetadataResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * subscription.getMetadata((err, apiResponse) => {
+     *   if (err) {
+     *     // Error handling omitted.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.getMetadata().then((data) => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     getMetadata(gaxOpts?: CallOptions): Promise<GetSubscriptionMetadataResponse>;
     getMetadata(callback: GetSubscriptionMetadataCallback): void;
     getMetadata(gaxOpts: CallOptions, callback: GetSubscriptionMetadataCallback): void;
+    /**
+     * @typedef {array} ModifyPushConfigResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback ModifyPushConfigCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Modify the push config for the subscription.
+     *
+     * @param {object} config The push config.
+     * @param {string} config.pushEndpoint A URL locating the endpoint to which
+     *     messages should be published.
+     * @param {object} config.attributes [PushConfig attributes](https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#google.pubsub.v1.PushConfig).
+     * @param {object} config.oidcToken If specified, Pub/Sub will generate and
+     *     attach an OIDC JWT token as an `Authorization` header in the HTTP
+     *     request for every pushed message. This object should have the same
+     *     structure as [OidcToken]{@link google.pubsub.v1.OidcToken}
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {ModifyPushConfigCallback} [callback] Callback function.
+     * @returns {Promise<ModifyPushConfigResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = pubsub.topic('my-topic');
+     * const subscription = topic.subscription('my-subscription');
+     *
+     * const pushConfig = {
+     *   pushEndpoint: 'https://mydomain.com/push',
+     *   attributes: {
+     *     key: 'value'
+     *   },
+     *   oidcToken: {
+     *     serviceAccountEmail: 'myproject@appspot.gserviceaccount.com',
+     *     audience: 'myaudience'
+     *   }
+     * };
+     *
+     * subscription.modifyPushConfig(pushConfig, (err, apiResponse) => {
+     *   if (err) {
+     *     // Error handling omitted.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.modifyPushConfig(pushConfig).then((data) => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     modifyPushConfig(config: PushConfig, gaxOpts?: CallOptions): Promise<EmptyResponse>;
     modifyPushConfig(config: PushConfig, callback: EmptyCallback): void;
     modifyPushConfig(config: PushConfig, gaxOpts: CallOptions, callback: EmptyCallback): void;
@@ -239,6 +588,7 @@ export declare class Subscription extends EventEmitter {
      * new `message` event listener which will also re-open the Subscription.
      *
      * @example
+     * ```
      * subscription.on('message', message => message.ack());
      *
      * // Close the subscription.
@@ -252,11 +602,89 @@ export declare class Subscription extends EventEmitter {
      *
      * // Resume receiving messages.
      * subscription.open();
+     * ```
      */
     open(): void;
+    /**
+     * @typedef {array} SeekResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback SeekCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Seeks an existing subscription to a point in time or a given snapshot.
+     *
+     * @param {string|date} snapshot The point to seek to. This will accept the
+     *     name of the snapshot or a Date object.
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {SeekCallback} [callback] Callback function.
+     * @returns {Promise<SeekResponse>}
+     *
+     * @example
+     * ```
+     * const callback = (err, resp) => {
+     *   if (!err) {
+     *     // Seek was successful.
+     *   }
+     * };
+     *
+     * subscription.seek('my-snapshot', callback);
+     *
+     * //-
+     * // Alternatively, to specify a certain point in time, you can provide a
+     * Date
+     * // object.
+     * //-
+     * const date = new Date('October 21 2015');
+     *
+     * subscription.seek(date, callback);
+     * ```
+     */
     seek(snapshot: string | Date, gaxOpts?: CallOptions): Promise<SeekResponse>;
     seek(snapshot: string | Date, callback: SeekCallback): void;
     seek(snapshot: string | Date, gaxOpts: CallOptions, callback: SeekCallback): void;
+    /**
+     * @typedef {array} SetSubscriptionMetadataResponse
+     * @property {object} 0 The full API response.
+     */
+    /**
+     * @callback SetSubscriptionMetadataCallback
+     * @param {?Error} err Request error, if any.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Update the subscription object.
+     *
+     * @param {object} metadata The subscription metadata.
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {SetSubscriptionMetadataCallback} [callback] Callback function.
+     * @returns {Promise<SetSubscriptionMetadataResponse>}
+     *
+     * @example
+     * ```
+     * const metadata = {
+     *   key: 'value'
+     * };
+     *
+     * subscription.setMetadata(metadata, (err, apiResponse) => {
+     *   if (err) {
+     *     // Error handling omitted.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * subscription.setMetadata(metadata).then((data) => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     setMetadata(metadata: SubscriptionMetadata, gaxOpts?: CallOptions): Promise<SetSubscriptionMetadataResponse>;
     setMetadata(metadata: SubscriptionMetadata, callback: SetSubscriptionMetadataCallback): void;
     setMetadata(metadata: SubscriptionMetadata, gaxOpts: CallOptions, callback: SetSubscriptionMetadataCallback): void;
@@ -276,7 +704,9 @@ export declare class Subscription extends EventEmitter {
      * @returns {Snapshot}
      *
      * @example
+     * ```
      * const snapshot = subscription.snapshot('my-snapshot');
+     * ```
      */
     snapshot(name: string): Snapshot;
     /**