1 | /// <reference types="node" />
|
2 | import { GoogleAuth, GoogleAuthOptions } from 'google-auth-library';
|
3 | import { CredentialBody } from 'google-auth-library';
|
4 | import * as r from 'teeny-request';
|
5 | import { Duplex, DuplexOptions, Readable, Writable } from 'stream';
|
6 | import { Interceptor } from './service-object';
|
7 | export declare type ResponseBody = any;
|
8 | export interface DuplexifyOptions extends DuplexOptions {
|
9 | autoDestroy?: boolean;
|
10 | end?: boolean;
|
11 | }
|
12 | export interface Duplexify extends Duplex {
|
13 | readonly destroyed: boolean;
|
14 | setWritable(writable: Writable | false | null): void;
|
15 | setReadable(readable: Readable | false | null): void;
|
16 | }
|
17 | export interface DuplexifyConstructor {
|
18 | obj(writable?: Writable | false | null, readable?: Readable | false | null, options?: DuplexifyOptions): Duplexify;
|
19 | new (writable?: Writable | false | null, readable?: Readable | false | null, options?: DuplexifyOptions): Duplexify;
|
20 | (writable?: Writable | false | null, readable?: Readable | false | null, options?: DuplexifyOptions): Duplexify;
|
21 | }
|
22 | export interface ParsedHttpRespMessage {
|
23 | resp: r.Response;
|
24 | err?: ApiError;
|
25 | }
|
26 | export interface MakeAuthenticatedRequest {
|
27 | (reqOpts: DecorateRequestOptions): Duplexify;
|
28 | (reqOpts: DecorateRequestOptions, options?: MakeAuthenticatedRequestOptions): void | Abortable;
|
29 | (reqOpts: DecorateRequestOptions, callback?: BodyResponseCallback): void | Abortable;
|
30 | (reqOpts: DecorateRequestOptions, optionsOrCallback?: MakeAuthenticatedRequestOptions | BodyResponseCallback): void | Abortable | Duplexify;
|
31 | getCredentials: (callback: (err?: Error | null, credentials?: CredentialBody) => void) => void;
|
32 | authClient: GoogleAuth;
|
33 | }
|
34 | export interface Abortable {
|
35 | abort(): void;
|
36 | }
|
37 | export declare type AbortableDuplex = Duplexify & Abortable;
|
38 | export interface PackageJson {
|
39 | name: string;
|
40 | version: string;
|
41 | }
|
42 | export interface MakeAuthenticatedRequestFactoryConfig extends GoogleAuthOptions {
|
43 | /**
|
44 | * Automatically retry requests if the response is related to rate limits or
|
45 | * certain intermittent server errors. We will exponentially backoff
|
46 | * subsequent requests by default. (default: true)
|
47 | */
|
48 | autoRetry?: boolean;
|
49 | /**
|
50 | * If true, just return the provided request options. Default: false.
|
51 | */
|
52 | customEndpoint?: boolean;
|
53 | /**
|
54 | * Account email address, required for PEM/P12 usage.
|
55 | */
|
56 | email?: string;
|
57 | /**
|
58 | * Maximum number of automatic retries attempted before returning the error.
|
59 | * (default: 3)
|
60 | */
|
61 | maxRetries?: number;
|
62 | stream?: Duplexify;
|
63 | /**
|
64 | * A pre-instantiated GoogleAuth client that should be used.
|
65 | * A new will be created if this is not set.
|
66 | */
|
67 | authClient?: GoogleAuth;
|
68 | }
|
69 | export interface MakeAuthenticatedRequestOptions {
|
70 | onAuthenticated: OnAuthenticatedCallback;
|
71 | }
|
72 | export interface OnAuthenticatedCallback {
|
73 | (err: Error | null, reqOpts?: DecorateRequestOptions): void;
|
74 | }
|
75 | export interface GoogleErrorBody {
|
76 | code: number;
|
77 | errors?: GoogleInnerError[];
|
78 | response: r.Response;
|
79 | message?: string;
|
80 | }
|
81 | export interface GoogleInnerError {
|
82 | reason?: string;
|
83 | message?: string;
|
84 | }
|
85 | export interface MakeWritableStreamOptions {
|
86 | /**
|
87 | * A connection instance used to get a token with and send the request
|
88 | * through.
|
89 | */
|
90 | connection?: {};
|
91 | /**
|
92 | * Metadata to send at the head of the request.
|
93 | */
|
94 | metadata?: {
|
95 | contentType?: string;
|
96 | };
|
97 | /**
|
98 | * Request object, in the format of a standard Node.js http.request() object.
|
99 | */
|
100 | request?: r.Options;
|
101 | makeAuthenticatedRequest(reqOpts: r.OptionsWithUri, fnobj: {
|
102 | onAuthenticated(err: Error | null, authenticatedReqOpts?: r.Options): void;
|
103 | }): void;
|
104 | }
|
105 | export interface DecorateRequestOptions extends r.CoreOptions {
|
106 | autoPaginate?: boolean;
|
107 | autoPaginateVal?: boolean;
|
108 | objectMode?: boolean;
|
109 | maxRetries?: number;
|
110 | uri: string;
|
111 | interceptors_?: Interceptor[];
|
112 | shouldReturnStream?: boolean;
|
113 | }
|
114 | export interface ParsedHttpResponseBody {
|
115 | body: ResponseBody;
|
116 | err?: Error;
|
117 | }
|
118 | /**
|
119 | * Custom error type for API errors.
|
120 | *
|
121 | * @param {object} errorBody - Error object.
|
122 | */
|
123 | export declare class ApiError extends Error {
|
124 | code?: number;
|
125 | errors?: GoogleInnerError[];
|
126 | response?: r.Response;
|
127 | constructor(errorMessage: string);
|
128 | constructor(errorBody: GoogleErrorBody);
|
129 | /**
|
130 | * Pieces together an error message by combining all unique error messages
|
131 | * returned from a single GoogleError
|
132 | *
|
133 | * @private
|
134 | *
|
135 | * @param {GoogleErrorBody} err The original error.
|
136 | * @param {GoogleInnerError[]} [errors] Inner errors, if any.
|
137 | * string}
{ |
138 | */
|
139 | static createMultiErrorMessage(err: GoogleErrorBody, errors?: GoogleInnerError[]): string;
|
140 | }
|
141 | /**
|
142 | * Custom error type for partial errors returned from the API.
|
143 | *
|
144 | * @param {object} b - Error object.
|
145 | */
|
146 | export declare class PartialFailureError extends Error {
|
147 | errors?: GoogleInnerError[];
|
148 | response?: r.Response;
|
149 | constructor(b: GoogleErrorBody);
|
150 | }
|
151 | export interface BodyResponseCallback {
|
152 | (err: Error | ApiError | null, body?: ResponseBody, res?: r.Response): void;
|
153 | }
|
154 | export interface MakeRequestConfig {
|
155 | /**
|
156 | * Automatically retry requests if the response is related to rate limits or
|
157 | * certain intermittent server errors. We will exponentially backoff
|
158 | * subsequent requests by default. (default: true)
|
159 | */
|
160 | autoRetry?: boolean;
|
161 | /**
|
162 | * Maximum number of automatic retries attempted before returning the error.
|
163 | * (default: 3)
|
164 | */
|
165 | maxRetries?: number;
|
166 | retries?: number;
|
167 | stream?: Duplexify;
|
168 | shouldRetryFn?: (response?: r.Response) => boolean;
|
169 | }
|
170 | export declare class Util {
|
171 | ApiError: typeof ApiError;
|
172 | PartialFailureError: typeof PartialFailureError;
|
173 | /**
|
174 | * No op.
|
175 | *
|
176 | * @example
|
177 | * function doSomething(callback) {
|
178 | * callback = callback || noop;
|
179 | * }
|
180 | */
|
181 | noop(): void;
|
182 | /**
|
183 | * Uniformly process an API response.
|
184 | *
|
185 | * @param {*} err - Error value.
|
186 | * @param {*} resp - Response value.
|
187 | * @param {*} body - Body value.
|
188 | * @param {function} callback - The callback function.
|
189 | */
|
190 | handleResp(err: Error | null, resp?: r.Response | null, body?: ResponseBody, callback?: BodyResponseCallback): void;
|
191 | /**
|
192 | * Sniff an incoming HTTP response message for errors.
|
193 | *
|
194 | * @param {object} httpRespMessage - An incoming HTTP response message from `request`.
|
195 | * @return {object} parsedHttpRespMessage - The parsed response.
|
196 | * @param {?error} parsedHttpRespMessage.err - An error detected.
|
197 | * @param {object} parsedHttpRespMessage.resp - The original response object.
|
198 | */
|
199 | parseHttpRespMessage(httpRespMessage: r.Response): ParsedHttpRespMessage;
|
200 | /**
|
201 | * Parse the response body from an HTTP request.
|
202 | *
|
203 | * @param {object} body - The response body.
|
204 | * @return {object} parsedHttpRespMessage - The parsed response.
|
205 | * @param {?error} parsedHttpRespMessage.err - An error detected.
|
206 | * @param {object} parsedHttpRespMessage.body - The original body value provided
|
207 | * will try to be JSON.parse'd. If it's successful, the parsed value will
|
208 | * be returned here, otherwise the original value and an error will be returned.
|
209 | */
|
210 | parseHttpRespBody(body: ResponseBody): ParsedHttpResponseBody;
|
211 | /**
|
212 | * Take a Duplexify stream, fetch an authenticated connection header, and
|
213 | * create an outgoing writable stream.
|
214 | *
|
215 | * @param {Duplexify} dup - Duplexify stream.
|
216 | * @param {object} options - Configuration object.
|
217 | * @param {module:common/connection} options.connection - A connection instance used to get a token with and send the request through.
|
218 | * @param {object} options.metadata - Metadata to send at the head of the request.
|
219 | * @param {object} options.request - Request object, in the format of a standard Node.js http.request() object.
|
220 | * @param {string=} options.request.method - Default: "POST".
|
221 | * @param {string=} options.request.qs.uploadType - Default: "multipart".
|
222 | * @param {string=} options.streamContentType - Default: "application/octet-stream".
|
223 | * @param {function} onComplete - Callback, executed after the writable Request stream has completed.
|
224 | */
|
225 | makeWritableStream(dup: Duplexify, options: MakeWritableStreamOptions, onComplete?: Function): void;
|
226 | /**
|
227 | * Returns true if the API request should be retried, given the error that was
|
228 | * given the first time the request was attempted. This is used for rate limit
|
229 | * related errors as well as intermittent server errors.
|
230 | *
|
231 | * @param {error} err - The API error to check if it is appropriate to retry.
|
232 | * @return {boolean} True if the API request should be retried, false otherwise.
|
233 | */
|
234 | shouldRetryRequest(err?: ApiError): boolean;
|
235 | /**
|
236 | * Get a function for making authenticated requests.
|
237 | *
|
238 | * @param {object} config - Configuration object.
|
239 | * @param {boolean=} config.autoRetry - Automatically retry requests if the
|
240 | * response is related to rate limits or certain intermittent server
|
241 | * errors. We will exponentially backoff subsequent requests by default.
|
242 | * (default: true)
|
243 | * @param {object=} config.credentials - Credentials object.
|
244 | * @param {boolean=} config.customEndpoint - If true, just return the provided request options. Default: false.
|
245 | * @param {string=} config.email - Account email address, required for PEM/P12 usage.
|
246 | * @param {number=} config.maxRetries - Maximum number of automatic retries attempted before returning the error. (default: 3)
|
247 | * @param {string=} config.keyFile - Path to a .json, .pem, or .p12 keyfile.
|
248 | * @param {array} config.scopes - Array of scopes required for the API.
|
249 | */
|
250 | makeAuthenticatedRequestFactory(config: MakeAuthenticatedRequestFactoryConfig): MakeAuthenticatedRequest;
|
251 | /**
|
252 | * Make a request through the `retryRequest` module with built-in error
|
253 | * handling and exponential back off.
|
254 | *
|
255 | * @param {object} reqOpts - Request options in the format `request` expects.
|
256 | * @param {object=} config - Configuration object.
|
257 | * @param {boolean=} config.autoRetry - Automatically retry requests if the
|
258 | * response is related to rate limits or certain intermittent server
|
259 | * errors. We will exponentially backoff subsequent requests by default.
|
260 | * (default: true)
|
261 | * @param {number=} config.maxRetries - Maximum number of automatic retries
|
262 | * attempted before returning the error. (default: 3)
|
263 | * @param {object=} config.request - HTTP module for request calls.
|
264 | * @param {function} callback - The callback function.
|
265 | */
|
266 | makeRequest(reqOpts: DecorateRequestOptions, config: MakeRequestConfig, callback: BodyResponseCallback): void | Abortable;
|
267 | /**
|
268 | * Decorate the options about to be made in a request.
|
269 | *
|
270 | * @param {object} reqOpts - The options to be passed to `request`.
|
271 | * @param {string} projectId - The project ID.
|
272 | * @return {object} reqOpts - The decorated reqOpts.
|
273 | */
|
274 | decorateRequest(reqOpts: DecorateRequestOptions, projectId: string): DecorateRequestOptions;
|
275 | isCustomType(unknown: any, module: string): boolean;
|
276 | /**
|
277 | * Create a properly-formatted User-Agent string from a package.json file.
|
278 | *
|
279 | * @param {object} packageJson - A module's package.json file.
|
280 | * @return {string} userAgent - The formatted User-Agent string.
|
281 | */
|
282 | getUserAgentFromPackageJson(packageJson: PackageJson): string;
|
283 | /**
|
284 | * Given two parameters, figure out if this is either:
|
285 | * - Just a callback function
|
286 | * - An options object, and then a callback function
|
287 | * @param optionsOrCallback An options object or callback.
|
288 | * @param cb A potentially undefined callback.
|
289 | */
|
290 | maybeOptionsOrCallback<T = {}, C = (err?: Error) => void>(optionsOrCallback?: T | C, cb?: C): [T, C];
|
291 | }
|
292 | declare const util: Util;
|
293 | export { util };
|