feat: add categories and categories:create

README.md

@@ -219,6 +219,24 @@ If you are logged in, this will open the project in your browser:
 rdme open
 ```
 
+### Categories
+
+#### Get All Categories Associated to Your Project Version
+
+```sh
+rdme categories --version={project-version}
+```
+
+#### Create a New Category for your Project Version
+
+You can create a new category with a specified `title` and `type` for your project version. The `title` 
+will be converted to a slug in param case. If a category already exists with the same slug and type for
+the specified version then a new category is not created and the id of the existing category is returned. This includes if the slug contains incremented suffix such as `-1` or `-2`. If there are multiple categories with a matching slug and type then only one matching category is returned.
+
+```sh
+rdme categories:create <title> --categoryType ={category-type} --version={project-version}
+```
+
 ## Future
 
 We are continually expanding and improving the offerings of this application as we expand our public API and are able. Some interactions may change over time, but we will do our best to retain backwards compatibility.

__tests__/cmds/categories.test.js

@@ -0,0 +1,177 @@
+const nock = require('nock');
+
+const getApiNock = require('../get-api-nock');
+
+const CategoriesCommand = require('../../src/cmds/categories');
+const CategoriesCreateCommand = require('../../src/cmds/categories/create');
+
+const categories = new CategoriesCommand();
+const categoriesCreate = new CategoriesCreateCommand();
+
+const key = 'API_KEY';
+const version = '1.0.0';
+
+function getNockWithVersionHeader(v) {
+  return getApiNock({
+    'x-readme-version': v,
+  });
+}
+
+describe('rdme categories', () => {
+  beforeAll(() => nock.disableNetConnect());
+
+  afterEach(() => nock.cleanAll());
+
+  it('should error if no api key provided', () => {
+    return expect(categories.run({})).rejects.toThrow('No project API key provided. Please use `--key`.');
+  });
+
+  it('should return all categories for a single pages', async () => {
+    const getMock = getNockWithVersionHeader(version)
+      .persist()
+      .get('/api/v1/categories?perPage=10&page=1')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'One Category', slug: 'one-category', type: 'guide' }], {
+        'x-total-count': '1',
+      });
+
+    const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });
+
+    await expect(categories.run({ key, version: '1.0.0' })).resolves.toBe(
+      JSON.stringify([{ title: 'One Category', slug: 'one-category', type: 'guide' }], null, 2)
+    );
+
+    getMock.done();
+    versionMock.done();
+  });
+
+  it('should return all categories for multiple pages', async () => {
+    const getMock = getNockWithVersionHeader(version)
+      .persist()
+      .get('/api/v1/categories?perPage=10&page=1')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'One Category', slug: 'one-category', type: 'guide' }], {
+        'x-total-count': '17',
+      })
+      .get('/api/v1/categories?perPage=10&page=2')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'Another Category', slug: 'another-category', type: 'guide' }], {
+        'x-total-count': '17',
+      });
+
+    const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });
+
+    await expect(categories.run({ key, version: '1.0.0' })).resolves.toBe(
+      JSON.stringify(
+        [
+          { title: 'One Category', slug: 'one-category', type: 'guide' },
+          { title: 'Another Category', slug: 'another-category', type: 'guide' },
+        ],
+        null,
+        2
+      )
+    );
+
+    getMock.done();
+    versionMock.done();
+  });
+});
+
+describe('rdme categories:create', () => {
+  beforeAll(() => nock.disableNetConnect());
+
+  afterEach(() => nock.cleanAll());
+
+  it('should error if no api key provided', () => {
+    return expect(categoriesCreate.run({})).rejects.toThrow('No project API key provided. Please use `--key`.');
+  });
+
+  it('should error if no title provided', () => {
+    return expect(categoriesCreate.run({ key: '123' })).rejects.toThrow(
+      'No title provided. Usage `rdme categories:create <title> [options]`.'
+    );
+  });
+
+  it('should error if categoryType is blank', () => {
+    return expect(categoriesCreate.run({ key: '123', title: 'Test Title' })).rejects.toThrow(
+      '`categoryType` must be guide or reference.'
+    );
+  });
+
+  it('should error if categoryType is not `guide` or `reference`', () => {
+    return expect(categoriesCreate.run({ key: '123', title: 'Test Title', categoryType: 'test' })).rejects.toThrow(
+      '`categoryType` must be guide or reference.'
+    );
+  });
+
+  it('should create a new category if the slug and type do not match', async () => {
+    const getMock = getNockWithVersionHeader(version)
+      .persist()
+      .get('/api/v1/categories?perPage=10&page=1')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'Existing Category', slug: 'existing-category', type: 'guide' }], {
+        'x-total-count': '1',
+      });
+
+    const postMock = getNockWithVersionHeader(version)
+      .post('/api/v1/categories')
+      .basicAuth({ user: key })
+      .reply(201, { title: 'New Category', slug: 'new-category', type: 'guide', id: '123' });
+
+    const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });
+
+    await expect(
+      categoriesCreate.run({ title: 'New Category', categoryType: 'guide', key, version: '1.0.0' })
+    ).resolves.toBe("🌱 successfully created 'new-category' with a type of 'guide' and an id of '123'");
+
+    getMock.done();
+    postMock.done();
+    versionMock.done();
+  });
+
+  it('should create a new category if the slug matches but the type does not match', async () => {
+    const getMock = getNockWithVersionHeader(version)
+      .persist()
+      .get('/api/v1/categories?perPage=10&page=1')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'Category', slug: 'category', type: 'guide' }], {
+        'x-total-count': '1',
+      });
+
+    const postMock = getNockWithVersionHeader(version)
+      .post('/api/v1/categories')
+      .basicAuth({ user: key })
+      .reply(201, { title: 'Category', slug: 'category', type: 'reference', id: '123' });
+
+    const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });
+
+    await expect(
+      categoriesCreate.run({ title: 'Category', categoryType: 'reference', key, version: '1.0.0' })
+    ).resolves.toBe("🌱 successfully created 'category' with a type of 'reference' and an id of '123'");
+
+    getMock.done();
+    postMock.done();
+    versionMock.done();
+  });
+
+  it('should not create a new category if the slug and type match', async () => {
+    const getMock = getNockWithVersionHeader(version)
+      .persist()
+      .get('/api/v1/categories?perPage=10&page=1')
+      .basicAuth({ user: key })
+      .reply(200, [{ title: 'Category', slug: 'category', type: 'guide', id: '123' }], {
+        'x-total-count': '1',
+      });
+
+    const versionMock = getApiNock().get(`/api/v1/version/${version}`).basicAuth({ user: key }).reply(200, { version });
+
+    await expect(
+      categoriesCreate.run({ title: 'Category', categoryType: 'guide', key, version: '1.0.0' })
+    ).resolves.toBe(
+      "The 'category' category with a type of 'guide' already exists with an id of '123'. A new category was not created"
+    );
+
+    getMock.done();
+    versionMock.done();
+  });
+});

package.json

@@ -36,6 +36,7 @@
   "dependencies": {
     "@actions/core": "^1.6.0",
     "chalk": "^4.1.2",
+    "change-case": "^4.1.2",
     "cli-table": "^0.3.1",
     "command-line-args": "^5.2.0",
     "command-line-usage": "^6.0.2",

src/cmds/categories/create.js

@@ -0,0 +1,121 @@
+const chalk = require('chalk');
+const config = require('config');
+const changeCase = require('change-case');
+const { getProjectVersion } = require('../../lib/versionSelect');
+const fetch = require('../../lib/fetch');
+const { cleanHeaders, handleRes } = require('../../lib/fetch');
+const { debug } = require('../../lib/logger');
+
+module.exports = class CategoriesCreateCommand {
+  constructor() {
+    this.command = 'categories:create';
+    this.usage = 'categories:create <title> [options]';
+    this.description = 'Create a category with the specified title and guide in your ReadMe project';
+    this.category = 'categories';
+    this.position = 2;
+
+    this.hiddenargs = ['title'];
+    this.args = [
+      {
+        name: 'key',
+        type: String,
+        description: 'Project API key',
+      },
+      {
+        name: 'version',
+        type: String,
+        description: 'Project version',
+      },
+      {
+        name: 'title',
+        type: String,
+        defaultOption: true,
+      },
+      {
+        name: 'categoryType',
+        type: String,
+        description: 'Category type, must be guide or reference',
+      },
+    ];
+  }
+
+  async run(opts) {
+    const { categoryType, title, key, version } = opts;
+    debug(`command: ${this.command}`);
+    debug(`opts: ${JSON.stringify(opts)}`);
+
+    if (!key) {
+      return Promise.reject(new Error('No project API key provided. Please use `--key`.'));
+    }
+
+    if (!title) {
+      return Promise.reject(new Error(`No title provided. Usage \`${config.get('cli')} ${this.usage}\`.`));
+    }
+
+    if (categoryType !== 'guide' && categoryType !== 'reference') {
+      return Promise.reject(new Error('`categoryType` must be guide or reference.'));
+    }
+
+    const selectedVersion = await getProjectVersion(version, key, false);
+
+    debug(`selectedVersion: ${selectedVersion}`);
+
+    const slug = changeCase.paramCase(title);
+
+    function getNumberOfPages() {
+      return fetch(`${config.get('host')}/api/v1/categories?perPage=10&page=1`, {
+        method: 'get',
+        headers: cleanHeaders(key, {
+          'x-readme-version': selectedVersion,
+          Accept: 'application/json',
+        }),
+      }).then(res => {
+        return Math.ceil(res.headers.get('x-total-count') / 10);
+      });
+    }
+
+    const allCategories = [].concat(
+      ...(await Promise.all(
+        Array.from({ length: await getNumberOfPages() }, (_, i) => i + 1).map(async page => {
+          return fetch(`${config.get('host')}/api/v1/categories?perPage=10&page=${page}`, {
+            method: 'get',
+            headers: cleanHeaders(key, {
+              'x-readme-version': selectedVersion,
+              Accept: 'application/json',
+            }),
+          }).then(res => handleRes(res));
+        })
+      ))
+    );
+
+    async function matchCategory() {
+      return allCategories.filter(category => {
+        return category.slug.match(`${slug}(-\\d)?`) && category.type === categoryType;
+      });
+    }
+
+    async function createCategory() {
+      const matchedCategory = await matchCategory();
+      if (matchedCategory.length > 0) {
+        return `The '${matchedCategory[0].slug}' category with a type of '${matchedCategory[0].type}' already exists with an id of '${matchedCategory[0].id}'. A new category was not created`;
+      }
+      return fetch(`${config.get('host')}/api/v1/categories`, {
+        method: 'post',
+        headers: cleanHeaders(key, {
+          'x-readme-version': selectedVersion,
+          'Content-Type': 'application/json',
+        }),
+        body: JSON.stringify({
+          title,
+          type: categoryType,
+        }),
+      })
+        .then(res => handleRes(res))
+        .then(res => `🌱 successfully created '${res.slug}' with a type of '${res.type}' and an id of '${res.id}'`);
+    }
+
+    const createdCategory = chalk.green(await createCategory());
+
+    return createdCategory;
+  }
+};