@google-cloud/pubsub 2.18.1 → 2.18.5

package/build/src/pubsub.d.ts

@@ -126,18 +126,24 @@ interface GetClientCallback {
  *
  * @param {ClientConfig} [options] Configuration options.
  *
- * @example <caption>Import the client library</caption>
+ * @example Import the client library
+ * ```
  * const {PubSub} = require('@google-cloud/pubsub');
  *
- * @example <caption>Create a client that uses <a href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application Default Credentials (ADC)</a>:</caption>
+ * ```
+ * @example Create a client that uses <a href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application Default Credentials (ADC)</a>:
+ * ```
  * const pubsub = new PubSub();
  *
- * @example <caption>Create a client with <a href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit credentials</a>:</caption>
+ * ```
+ * @example Create a client with <a href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit credentials</a>:
+ * ```
  * const pubsub = new PubSub({
  *   projectId: 'your-project-id',
  *   keyFilename: '/path/to/keyfile.json'
  * });
  *
+ * ```
  * @example <caption>include:samples/quickstart.js</caption>
  * region_tag:pubsub_quickstart_create_topic
  * Full quickstart example:
@@ -164,6 +170,17 @@ export declare class PubSub {
      * @returns {boolean} true if the name is resolved.
      */
     get isIdResolved(): boolean;
+    /**
+     * Closes out this object, releasing any server connections. Note that once
+     * you close a PubSub object, it may not be used again. Any pending operations
+     * (e.g. queued publish messages) will fail. If you have topic or subscription
+     * objects that may have pending operations, you should call close() on those
+     * first if you want any pending messages to be delivered correctly. The
+     * PubSub class doesn't track those.
+     *
+     * @callback EmptyCallback
+     * @returns {Promise<void>}
+     */
     close(): Promise<void>;
     close(callback: EmptyCallback): void;
     /**
@@ -183,7 +200,8 @@ export declare class PubSub {
      *   here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
      * @returns {Promise<Schema>}
      *
-     * @example <caption>Create a schema.</caption>
+     * @example Create a schema.
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
@@ -192,14 +210,171 @@ export declare class PubSub {
      *   SchemaTypes.Avro,
      *   '{...avro definition...}'
      * );
+     * ```
      */
     createSchema(schemaId: string, type: SchemaType, definition: string, gaxOpts?: CallOptions): Promise<Schema>;
+    /**
+     * @typedef {array} CreateSubscriptionResponse
+     * @property {Subscription} 0 The new {@link Subscription}.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback CreateSubscriptionCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Subscription} Subscription
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Options for creating a subscription.
+     *
+     * See a [Subscription
+     * resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions).
+     *
+     * @typedef {object} CreateSubscriptionRequest
+     * @property {DeadLetterPolicy} [deadLetterPolicy] A policy that specifies the
+     *     conditions for dead lettering messages in this subscription.
+     * @property {object} [flowControl] Flow control configurations for
+     *     receiving messages. Note that these options do not persist across
+     *     subscription instances.
+     * @property {number} [flowControl.maxBytes] The maximum number of bytes
+     *     in un-acked messages to allow before the subscription pauses incoming
+     *     messages. Defaults to 20% of free memory.
+     * @property {number} [flowControl.maxMessages=Infinity] The maximum number
+     *     of un-acked messages to allow before the subscription pauses incoming
+     *     messages.
+     * @property {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @property {number|google.protobuf.Duration} [messageRetentionDuration] Set
+     *     this to override the default duration of 7 days. This value is expected
+     *     in seconds. Acceptable values are in the range of 10 minutes and 7
+     *     days.
+     * @property {string} [pushEndpoint] A URL to a custom endpoint that
+     *     messages should be pushed to.
+     * @property {object} [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}
+     * @property {boolean} [retainAckedMessages=false] If set, acked messages
+     *     are retained in the subscription's backlog for the length of time
+     *     specified by `options.messageRetentionDuration`.
+     * @property {ExpirationPolicy} [expirationPolicy] A policy that specifies
+     *     the conditions for this subscription's expiration.
+     */
+    /**
+     * Create a subscription to a topic.
+     *
+     * @see [Subscriptions: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create}
+     * @see {@link Topic#createSubscription}
+     *
+     * @throws {Error} If a Topic instance or topic name is not provided.
+     * @throws {Error} If a subscription name is not provided.
+     *
+     * @param {Topic|string} topic The Topic to create a subscription to.
+     * @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 Subscribe to a topic.
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * const topic = 'messageCenter';
+     * const name = 'newMessages';
+     *
+     * const callback = function(err, subscription, apiResponse) {};
+     *
+     * pubsub.createSubscription(topic, name, callback);
+     *
+     * ```
+     * @example If the callback is omitted, we'll return a Promise.
+     * ```
+     * pubsub.createSubscription(topic, name)
+     *   .then(function(data) {
+     *     const subscription = data[0];
+     *     const apiResponse = data[1];
+     *   });
+     * ```
+     */
     createSubscription(topic: Topic | string, name: string, options?: CreateSubscriptionOptions): Promise<CreateSubscriptionResponse>;
     createSubscription(topic: Topic | string, name: string, callback: CreateSubscriptionCallback): void;
     createSubscription(topic: Topic | string, name: string, options: CreateSubscriptionOptions, callback: CreateSubscriptionCallback): void;
+    /**
+     * @typedef {array} CreateTopicResponse
+     * @property {Topic} 0 The new {@link Topic}.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback CreateTopicCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Topic} topic The new {@link Topic}.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Create a topic with the given name.
+     *
+     * @see [Topics: create API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create}
+     *
+     * @param {string} name Name of the topic.
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {CreateTopicCallback} [callback] Callback function.
+     * @returns {Promise<CreateTopicResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * pubsub.createTopic('my-new-topic', function(err, topic, apiResponse) {
+     *   if (!err) {
+     *     // The topic was created successfully.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * pubsub.createTopic('my-new-topic').then(function(data) {
+     *   const topic = data[0];
+     *   const apiResponse = data[1];
+     * });
+     * ```
+     */
     createTopic(name: string | TopicMetadata, gaxOpts?: CallOptions): Promise<CreateTopicResponse>;
     createTopic(name: string | TopicMetadata, callback: CreateTopicCallback): void;
     createTopic(name: string | TopicMetadata, gaxOpts: CallOptions, callback: CreateTopicCallback): void;
+    /**
+     * Detach a subscription with the given name.
+     *
+     * @see [Admin: Pub/Sub administration API Documentation]{@link https://cloud.google.com/pubsub/docs/admin}
+     *
+     * @param {string} name Name of the subscription.
+     * @param {object} [gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @param {DetachSubscriptionCallback} [callback] Callback function.
+     * @returns {Promise<DetachSubscriptionResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * pubsub.detachSubscription('my-sub', (err, topic, apiResponse) => {
+     *   if (!err) {
+     *     // The topic was created successfully.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * pubsub.detachSubscription('my-sub').then(data => {
+     *   const apiResponse = data[0];
+     * });
+     * ```
+     */
     detachSubscription(name: string, gaxOpts?: CallOptions): Promise<DetachSubscriptionResponse>;
     detachSubscription(name: string, callback: DetachSubscriptionCallback): void;
     detachSubscription(name: string, gaxOpts: CallOptions, callback: DetachSubscriptionCallback): void;
@@ -237,17 +412,184 @@ export declare class PubSub {
      * @returns {AsyncIterable<ISchema>}
      *
      * @example
+     * ```
      * for await (const s of pubsub.listSchemas()) {
      *   const moreInfo = await s.get();
      * }
+     * ```
      */
     listSchemas(view?: SchemaView, options?: CallOptions): AsyncIterable<google.pubsub.v1.ISchema>;
+    /**
+     * Query object for listing snapshots.
+     *
+     * @typedef {object} GetSnapshotsRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {object} [options.gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @property {number} [options.pageSize] Maximum number of results to return.
+     * @property {string} [options.pageToken] Page token.
+     */
+    /**
+     * @typedef {array} GetSnapshotsResponse
+     * @property {Snapshot[]} 0 Array of {@link Snapshot} instances.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetSnapshotsCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Snapshot[]} snapshots Array of {@link Snapshot} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get a list of snapshots.
+     *
+     * @param {GetSnapshotsRequest} [query] Query object for listing snapshots.
+     * @param {GetSnapshotsCallback} [callback] Callback function.
+     * @returns {Promise<GetSnapshotsResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * pubsub.getSnapshots(function(err, snapshots) {
+     *   if (!err) {
+     *     // snapshots is an array of Snapshot objects.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * pubsub.getSnapshots().then(function(data) {
+     *   const snapshots = data[0];
+     * });
+     * ```
+     */
     getSnapshots(options?: PageOptions): Promise<GetSnapshotsResponse>;
     getSnapshots(callback: GetSnapshotsCallback): void;
     getSnapshots(options: PageOptions, callback: GetSnapshotsCallback): void;
+    /**
+     * Query object for listing subscriptions.
+     *
+     * @typedef {object} GetSubscriptionsRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {object} [options.gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @property {number} [options.pageSize] Maximum number of results to return.
+     * @property {string} [options.pageToken] Page token.
+     * @param {string|Topic} options.topic - The name of the topic to
+     *     list subscriptions from.
+     */
+    /**
+     * @typedef {array} GetSubscriptionsResponse
+     * @property {Subscription[]} 0 Array of {@link Subscription} instances.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetSubscriptionsCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Subscription[]} subscriptions Array of {@link Subscription} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get a list of the subscriptions registered to all of your project's topics.
+     * You may optionally provide a query object as the first argument to
+     * customize the response.
+     *
+     * Your provided callback will be invoked with an error object if an API error
+     * occurred or an array of {@link Subscription} objects.
+     *
+     * To get subscriptions for a topic, see {@link Topic}.
+     *
+     * @see [Subscriptions: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list}
+     *
+     * @param {GetSubscriptionsRequest} [query] Query object for listing subscriptions.
+     * @param {GetSubscriptionsCallback} [callback] Callback function.
+     * @returns {Promise<GetSubscriptionsResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * pubsub.getSubscriptions(function(err, subscriptions) {
+     *   if (!err) {
+     *     // subscriptions is an array of Subscription objects.
+     *   }
+     * });
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * pubsub.getSubscriptions().then(function(data) {
+     *   const subscriptions = data[0];
+     * });
+     * ```
+     */
     getSubscriptions(options?: GetSubscriptionsOptions): Promise<GetSubscriptionsResponse>;
     getSubscriptions(callback: GetSubscriptionsCallback): void;
     getSubscriptions(options: GetSubscriptionsOptions, callback: GetSubscriptionsCallback): void;
+    /**
+     * Query object for listing topics.
+     *
+     * @typedef {object} GetTopicsRequest
+     * @property {boolean} [autoPaginate=true] Have pagination handled
+     *     automatically.
+     * @property {object} [options.gaxOpts] Request configuration options, outlined
+     *     here: https://googleapis.github.io/gax-nodejs/interfaces/CallOptions.html.
+     * @property {number} [options.pageSize] Maximum number of results to return.
+     * @property {string} [options.pageToken] Page token.
+     */
+    /**
+     * @typedef {array} GetTopicsResponse
+     * @property {Topic[]} 0 Array of {@link Topic} instances.
+     * @property {object} 1 The full API response.
+     */
+    /**
+     * @callback GetTopicsCallback
+     * @param {?Error} err Request error, if any.
+     * @param {Topic[]} topics Array of {@link Topic} instances.
+     * @param {object} apiResponse The full API response.
+     */
+    /**
+     * Get a list of the topics registered to your project. You may optionally
+     * provide a query object as the first argument to customize the response.
+     *
+     * @see [Topics: list API Documentation]{@link https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list}
+     *
+     * @param {GetTopicsRequest} [query] Query object for listing topics.
+     * @param {GetTopicsCallback} [callback] Callback function.
+     * @returns {Promise<GetTopicsResponse>}
+     *
+     * @example
+     * ```
+     * const {PubSub} = require('@google-cloud/pubsub');
+     * const pubsub = new PubSub();
+     *
+     * pubsub.getTopics(function(err, topics) {
+     *   if (!err) {
+     *     // topics is an array of Topic objects.
+     *   }
+     * });
+     *
+     * //-
+     * // Customize the query.
+     * //-
+     * pubsub.getTopics({
+     *   pageSize: 3
+     * }, function(err, topics) {});
+     *
+     * //-
+     * // If the callback is omitted, we'll return a Promise.
+     * //-
+     * pubsub.getTopics().then(function(data) {
+     *   const topics = data[0];
+     * });
+     * ```
+     */
     getTopics(options?: PageOptions): Promise<GetTopicsResponse>;
     getTopics(callback: GetTopicsCallback): void;
     getTopics(options: PageOptions, callback: GetTopicsCallback): void;
@@ -327,10 +669,12 @@ export declare class PubSub {
      * @returns {Schema} A {@link Schema} instance.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
      * const schema = pubsub.schema('my-schema');
+     * ```
      */
     schema(idOrName: string): Schema;
     /**
@@ -343,10 +687,12 @@ export declare class PubSub {
      * @returns {Snapshot} A {@link Snapshot} instance.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
      * const snapshot = pubsub.snapshot('my-snapshot');
+     * ```
      */
     snapshot(name: string): Snapshot;
     /**
@@ -361,6 +707,7 @@ export declare class PubSub {
      * @returns {Subscription} A {@link Subscription} instance.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
@@ -375,6 +722,7 @@ export declare class PubSub {
      *   // message.attributes = Attributes of the message.
      *   // message.publishTime = Date when Pub/Sub received the message.
      * });
+     * ```
      */
     subscription(name: string, options?: SubscriptionOptions): Subscription;
     /**
@@ -387,10 +735,12 @@ export declare class PubSub {
      * @returns {Topic} A {@link Topic} instance.
      *
      * @example
+     * ```
      * const {PubSub} = require('@google-cloud/pubsub');
      * const pubsub = new PubSub();
      *
      * const topic = pubsub.topic('my-topic');
+     * ```
      */
     topic(name: string, options?: PublishOptions): Topic;
     /**