v2 of API

.github/workflows/ci.yaml

@@ -23,7 +23,7 @@ jobs:
  echo API_TOKEN=${{ secrets.API_TOKEN }} >> .env
  - run: npm run build
  - run: npm run test:unit
- - run: npm run test:e2e
+ - run: npm run test:integration
  - run: npm run lint
  env:
  CI: true

package.json

@@ -11,13 +11,13 @@
  "scripts": {
  "build": "tsc",
  "prepublishOnly": "npm run build && npm run test && npm run lint",
- "test": "npm run test:unit && npm run test:e2e",
  "prettier": "prettier --write src",
  "doc": "typedoc --name \"Confluence.js - Cloud and Server API library\" --out docs ./src/index.ts --plugin typedoc-plugin-extras --footerDate --footerTime --footerTypedocVersion --favicon https://svgshare.com/i/bVi.svg",
  "lint": "eslint src tests --ext .ts",
  "lint:fix": "npm run lint -- --fix",
+ "test": "npm run test:unit && npm run test:integration",
  "test:unit": "ava tests/unit",
- "test:e2e": "ava --timeout=2m --fail-fast --no-worker-threads -c 1 -s tests/e2e/**/*.test.ts"
+ "test:integration": "ava --timeout=2m --fail-fast --no-worker-threads -c 1 -s tests/integration/**.test.ts"
  },
  "ava": {
  "extensions": [
@@ -42,32 +42,32 @@
  "atlassian"
  ],
  "devDependencies": {
- "@swc-node/register": "^1.6.5",
+ "@swc-node/register": "^1.6.6",
  "@swc/helpers": "^0.5.1",
  "@types/express": "^4.17.17",
  "@types/oauth": "^0.9.1",
  "@types/sinon": "^10.0.15",
- "@typescript-eslint/eslint-plugin": "^5.59.9",
- "@typescript-eslint/parser": "^5.59.9",
- "ava": "^5.3.0",
- "dotenv": "^16.1.4",
- "eslint": "^8.42.0",
+ "@typescript-eslint/eslint-plugin": "^5.60.1",
+ "@typescript-eslint/parser": "^5.60.1",
+ "ava": "^5.3.1",
+ "dotenv": "^16.3.1",
+ "eslint": "^8.44.0",
  "eslint-config-airbnb": "^19.0.4",
  "eslint-config-airbnb-typescript": "^17.0.0",
  "eslint-import-resolver-typescript": "^3.5.5",
  "eslint-plugin-import": "^2.27.5",
  "prettier": "^2.8.8",
  "prettier-plugin-jsdoc": "^0.4.2",
- "sinon": "^15.1.0",
+ "sinon": "^15.2.0",
  "typedoc": "^0.24.8",
  "typedoc-plugin-extras": "^2.3.3",
- "typescript": "^5.1.3"
+ "typescript": "^5.1.6"
  },
  "dependencies": {
  "atlassian-jwt": "^2.0.2",
  "axios": "^1.4.0",
  "form-data": "^4.0.0",
  "oauth": "^0.10.0",
- "tslib": "^2.5.3"
+ "tslib": "^2.6.0"
  }
 }

src/clients/baseClient.ts

@@ -1,4 +1,4 @@
-import { AuthenticationService } from '../services/authenticationService';
+import { AuthenticationService } from '../services';
 import type { Callback } from '../callback';
 import type { Client } from './client';
 import type { Config } from '../config';
@@ -84,6 +84,22 @@ export class BaseClient implements Client {
  return this.#instance;
  }
 
+ getResponseHandler<T>(callback?: Callback<T>) {
+ const callbackResponseHandler = callback && ((data: T): void => callback(null, data));
+ const defaultResponseHandler = (data: T): T => data;
+
+ return callbackResponseHandler ?? defaultResponseHandler;
+ }
+
+ getErrorHandler(callback?: Callback<never>) {
+ const callbackErrorHandler = callback && ((error: Config.Error) => callback(error));
+ const defaultErrorHandler = (error: Error) => {
+ throw error;
+ };
+
+ return callbackErrorHandler ?? defaultErrorHandler;
+ }
+
  async sendRequest<T>(requestConfig: RequestConfig, callback: never, telemetryData?: any): Promise<T>;
  async sendRequest<T>(requestConfig: RequestConfig, callback: Callback<T>, telemetryData?: any): Promise<void>;
  async sendRequest<T>(requestConfig: RequestConfig, callback: Callback<T> | never): Promise<void | T> {
@@ -102,23 +118,15 @@ export class BaseClient implements Client {
 
  const response = await this.instance.request<T>(modifiedRequestConfig);
 
- const callbackResponseHandler = callback && ((data: T): void => callback(null, data));
- const defaultResponseHandler = (data: T): T => data;
-
- const responseHandler = callbackResponseHandler ?? defaultResponseHandler;
+ const responseHandler = this.getResponseHandler(callback);
 
  this.config.middlewares?.onResponse?.(response.data);
 
  return responseHandler(response.data);
  } catch (e: any) {
  const err = this.config.newErrorHandling && e.isAxiosError ? e.response.data : e;
 
- const callbackErrorHandler = callback && ((error: Config.Error) => callback(error));
- const defaultErrorHandler = (error: Error) => {
- throw error;
- };
-
- const errorHandler = callbackErrorHandler ?? defaultErrorHandler;
+ const errorHandler = this.getErrorHandler(callback);
 
  this.config.middlewares?.onError?.(err);
 

src/clients/client.ts

@@ -1,7 +1,12 @@
 import type { Callback } from '../callback';
+import type { Config } from '../config';
 import type { RequestConfig } from '../requestConfig';
 
 export interface Client {
+ getResponseHandler<T>(callback?: Callback<T>): (data: T) => void;
+
+ getErrorHandler(callback?: Callback<never>): (error: Config.Error) => void;
+
  sendRequest<T>(requestConfig: RequestConfig, callback?: never, telemetryData?: any): Promise<T>;
  sendRequest<T>(requestConfig: RequestConfig, callback?: Callback<T>, telemetryData?: any): Promise<void>;
 }

src/clients/index.ts

@@ -2,3 +2,4 @@ export * from './baseClient';
 export * from './client';
 export * from './confluenceClient';
 export * from './serverClient';
+export * from './version2Client';

src/clients/version2Client.ts

@@ -0,0 +1,43 @@
+import { BaseClient } from './baseClient';
+import { Config } from '../config';
+import {
+ Attachment,
+ BlogPost,
+ Children,
+ Comment,
+ Content,
+ ContentProperties,
+ CustomContent,
+ Label,
+ Page,
+ Space,
+ SpaceProperties,
+ Task,
+ User,
+ Version,
+} from '../version2';
+
+export class Version2Client extends BaseClient {
+ constructor(config: Config) {
+ super({
+ ...config,
+ newErrorHandling: true,
+ apiPrefix: config.apiPrefix ?? '/wiki/api/v2',
+ });
+ }
+
+ attachment = new Attachment(this);
+ blogPost = new BlogPost(this);
+ children = new Children(this);
+ comment = new Comment(this);
+ content = new Content(this);
+ contentProperties = new ContentProperties(this);
+ customContent = new CustomContent(this);
+ label = new Label(this);
+ page = new Page(this);
+ space = new Space(this);
+ spaceProperties = new SpaceProperties(this);
+ task = new Task(this);
+ user = new User(this);
+ version = new Version(this);
+}

src/config.ts

@@ -11,9 +11,18 @@ export interface Config {
  telemetry?: Config.Telemetry;
  /** Adds `'X-Atlassian-Token': 'no-check'` to each request header */
  noCheckAtlassianToken?: boolean;
- /** Enable new API error handling. `false` by default. */
+ /**
+ * Enable new API error handling. For "ConfluenceClient" `false` by default.
+ *
+ * For "Version2Client" enabled by default.
+ */
  newErrorHandling?: boolean;
- /** Prefix for all API routes. */
+ /**
+ * Prefix for all API routes.
+ *
+ * - For "ConfluenceCloud" by default it is "/wiki/rest"
+ * - For "Version2Client" by default it is "/wiki/api/v2"
+ */
  apiPrefix?: string;
 }
 

src/index.ts

@@ -12,3 +12,7 @@ export * as Models from './api/models';
 export * as Parameters from './api/parameters';
 export * as ServerModels from './server/models';
 export * as ServerParameters from './server/parameters';
+
+export * as Version2 from './version2';
+export * as Version2Models from './version2/models';
+export * as Version2Parameters from './version2/parameters';

src/services/index.ts

@@ -0,0 +1,2 @@
+export * from './authenticationService';
+export * from './paginationService';

src/services/paginationService.ts

@@ -0,0 +1,90 @@
+import type { Pagination } from '../version2/models';
+
+/** This service is responsible for handling pagination. */
+export class PaginationService {
+ /**
+ * This method builds a paginated result based on the given pagination object and a function to call for the next
+ * page.
+ */
+ buildPaginatedResult<T>(
+ pagination: Pagination<T>,
+ callFn: (params: any) => Promise<Pagination<T>>,
+ ): Pagination<T> {
+ if (!pagination._links.next) {
+ return this.buildEmptyPagination(pagination);
+ }
+
+ const parameters = this.parseParameters(pagination._links.next);
+
+ return {
+ results: pagination.results,
+ _links: pagination._links,
+ parameters,
+ hasNext: true,
+ next: () => callFn(parameters),
+ getAll: () => this.getAll<T>(pagination.results, parameters, callFn),
+ };
+ }
+
+ private parseParameters(urlString: string) {
+ const url = new URL(urlString, 'http://temp.temp');
+ const searchParams = new URLSearchParams(url.search);
+ const paramsObject: Record<string, string> = {};
+
+ searchParams.forEach((value, key) => {
+ paramsObject[this.toCamelCase(key)] = value;
+ });
+
+ return paramsObject;
+ }
+
+ /** This method retrieves all pages of results. */
+ private async getAll<T>(
+ actualResult: T[],
+ params: Record<string, string>,
+ callFn: (params: Record<string, string>) => Promise<Pagination<T>>,
+ ): Promise<T[]> {
+ let hasNext = true;
+
+ while (hasNext) {
+ const paginationResult: Pagination<T> = await callFn(params);
+
+ actualResult.push(...paginationResult.results);
+
+ if (paginationResult._links.next) {
+ params = this.parseParameters(paginationResult._links.next);
+ } else {
+ hasNext = false;
+ }
+ }
+
+ return actualResult;
+ }
+
+ private toCamelCase(str: string): string {
+ return str.replace(/([-_][a-z])/gi, piece => {
+ return piece.toUpperCase().replace('-', '').replace('_', '');
+ });
+ }
+
+ private buildEmptyPagination<T>(pagination: Pagination<T>): Pagination<T> {
+ const emptyPagination: Pagination<T> = {
+ results: pagination.results,
+ parameters: pagination.parameters,
+ _links: {},
+ hasNext: false,
+ next: () =>
+ Promise.resolve({
+ results: [],
+ hasNext: false,
+ parameters: pagination.parameters,
+ _links: pagination._links,
+ next: emptyPagination.next,
+ getAll: () => Promise.resolve([]),
+ }),
+ getAll: () => Promise.resolve(pagination.results),
+ };
+
+ return emptyPagination;
+ }
+}