Add support for fullPath on methods. (#1200)

lib/StripeMethod.js

@@ -11,6 +11,8 @@ const makeAutoPaginationMethods = require('./autoPagination')
  * @param [spec.method='GET'] Request Method (POST, GET, DELETE, PUT)
  * @param [spec.path=''] Path to be appended to the API BASE_PATH, joined with
  * the instance's path (e.g. 'charges' or 'customers')
+ * @param [spec.fullPath=''] Fully qualified path to the method (eg. /v1/a/b/c).
+ * If this is specified, path should not be specified.
  * @param [spec.urlParams=[]] Array of required arguments in the order that they
  * must be passed by the consumer of the API. Subsequent optional arguments are
  * optionally passed through a hash (Object) as the penultimate argument
@@ -20,11 +22,16 @@ const makeAutoPaginationMethods = require('./autoPagination')
  * @param [spec.host] Hostname for the request.
  */
 function stripeMethod(spec) {
+ if (spec.path !== undefined && spec.fullPath !== undefined) {
+ throw new Error(
+ `Method spec specified both a 'path' (${spec.path}) and a 'fullPath' (${spec.fullPath}).`
+ );
+ }
  return function(...args) {
  const callback = typeof args[args.length - 1] == 'function' && args.pop();
 
  spec.urlParams = utils.extractUrlParams(
- this.createResourcePathWithSymbols(spec.path || '')
+ spec.fullPath || this.createResourcePathWithSymbols(spec.path || '')
  );
 
  const requestPromise = utils.callbackifyPromiseWithTimeout(

lib/makeRequest.js

@@ -4,11 +4,20 @@ const utils = require('./utils');
 
 function getRequestOpts(self, requestArgs, spec, overrideData) {
  // Extract spec values with defaults.
- const commandPath = utils.makeURLInterpolator(spec.path || '');
  const requestMethod = (spec.method || 'GET').toUpperCase();
  const urlParams = spec.urlParams || [];
  const encode = spec.encode || ((data) => data);
- const path = self.createResourcePathWithSymbols(spec.path);
+
+ const isUsingFullPath = !!spec.fullPath;
+ const commandPath = utils.makeURLInterpolator(
+ isUsingFullPath ? spec.fullPath : spec.path || ''
+ );
+
+ // When using fullPath, we ignore the resource path as it should already be
+ // fully qualified.
+ const path = isUsingFullPath
+ ? spec.fullPath
+ : self.createResourcePathWithSymbols(spec.path);
 
  // Don't mutate args externally.
  const args = [].slice.call(requestArgs);
@@ -39,7 +48,11 @@ function getRequestOpts(self, requestArgs, spec, overrideData) {
  );
  }
 
- const requestPath = self.createFullPath(commandPath, urlData);
+ // When using full path, we can just invoke the URL interpolator directly
+ // as we don't need to use the resource to create a full path.
+ const requestPath = isUsingFullPath
+ ? commandPath(urlData)
+ : self.createFullPath(commandPath, urlData);
  const headers = Object.assign(options.headers, spec.headers);
 
  if (spec.validator) {

test/StripeResource.spec.js

@@ -642,6 +642,38 @@ describe('StripeResource', () => {
  });
  });
 
+ describe('method with fullPath', () => {
+ it('interpolates in parameters', (callback) => {
+ const handleRequest = (req, res) => {
+ expect(req.url).to.equal('/v1/parent/hello/child/world');
+
+ // Write back JSON to close out the server.
+ res.write('{}');
+ res.end();
+ };
+
+ testUtils.getTestServerStripe(
+ {},
+ handleRequest,
+ (err, stripe, closeServer) => {
+ const resource = new (StripeResource.extend({
+ test: stripeMethod({
+ method: 'GET',
+ fullPath: '/v1/parent/{param1}/child/{param2}',
+ }),
+ }))(stripe);
+
+ return resource.test('hello', 'world', (err, res) => {
+ closeServer();
+ // Spot check that we received a response.
+ expect(res).to.deep.equal({});
+ return callback(err);
+ });
+ }
+ );
+ });
+ });
+
  describe('streaming', () => {
  /**
  * Defines a fake resource with a `pdf` method

test/makeRequest.spec.js

@@ -3,6 +3,7 @@
 require('../testUtils');
 
 const makeRequest = require('../lib/makeRequest');
+const utils = require('../lib/utils');
 const expect = require('chai').expect;
 
 describe('makeRequest', () => {
@@ -26,4 +27,42 @@ describe('makeRequest', () => {
  ]);
  });
  });
+
+ describe('makeRequest with fullPath', () => {
+ it('handles urlData', async () => {
+ const args = ['hello', 'world'];
+
+ const fullPath = '/v1/parent/{param1}/child/{param2}';
+ const spec = {
+ fullPath,
+ urlParams: utils.extractUrlParams(fullPath),
+ };
+
+ let actualPath;
+ const mockSelf = {
+ // These two methods shouldn't be called when using a fullPath, as they
+ // don't rely on the resource path.
+ createResourcePathWithSymbols: () => {
+ throw new Error('Unexpected call to createResourcePathWithSymbols.');
+ },
+ createFullPath: () => {
+ throw new Error('Unexpected call to createFullPath.');
+ },
+ _request: (
+ _method,
+ _host,
+ path,
+ _body,
+ _auth,
+ _headers,
+ requestCallback
+ ) => {
+ actualPath = path;
+ requestCallback(null, 'response');
+ },
+ };
+ await makeRequest(mockSelf, args, spec, {});
+ expect(actualPath).to.equal('/v1/parent/hello/child/world');
+ });
+ });
 });

types/lib.d.ts

@@ -16,7 +16,8 @@ declare module 'stripe' {
  >(spec: T): StripeResource & T;
  static method(spec: {
  method: string;
- path: string;
+ path?: string;
+ fullPath?: string;
  methodType?: 'list';
  }): (...args: any[]) => object; //eslint-disable-line @typescript-eslint/no-explicit-any
  static BASIC_METHODS: {

types/test/typescriptTest.ts

@@ -180,6 +180,10 @@ Stripe.StripeResource.extend({
  method: 'create',
  path: 'foo',
  }),
+ fooFullPath: Stripe.StripeResource.method({
+ method: 'create',
+ fullPath: '/v1/full/path',
+ }),
 });
 
 const maxBufferedRequestMetrics: number =