confluence.js 2.0.0 → 2.2.0-dev20260318121920

package/src/api/users.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class Users {
@@ -153,7 +153,8 @@ export class Users {
   }
 
   /**
-   * Returns user details for the ids provided in request.
+   * Returns user details for the ids provided in the request. Currently this API returns a maximum of 100 results. If
+   * more than 100 account ids are passed in, then the first 100 will be returned.
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
    * ('Can use' global permission).
@@ -163,7 +164,8 @@ export class Users {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Returns user details for the ids provided in request.
+   * Returns user details for the ids provided in the request. Currently this API returns a maximum of 100 results. If
+   * more than 100 account ids are passed in, then the first 100 will be returned.
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
    * ('Can use' global permission).
@@ -190,8 +192,10 @@ export class Users {
   }
 
   /**
-   * Returns a user's email address. This API is only available to apps approved by Atlassian, according to these
+   * Returns a user's email address regardless of the user’s profile visibility settings. For Connect apps, this API is
+   * only available to apps approved by Atlassian, according to these
    * [guidelines](https://community.developer.atlassian.com/t/guidelines-for-requesting-access-to-email-address/27603).
+   * For Forge apps, this API only supports access via asApp() requests.
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
    * ('Can use' global permission).
@@ -201,8 +205,10 @@ export class Users {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Returns a user's email address. This API is only available to apps approved by Atlassian, according to these
+   * Returns a user's email address regardless of the user’s profile visibility settings. For Connect apps, this API is
+   * only available to apps approved by Atlassian, according to these
    * [guidelines](https://community.developer.atlassian.com/t/guidelines-for-requesting-access-to-email-address/27603).
+   * For Forge apps, this API only supports access via asApp() requests.
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
    * ('Can use' global permission).
@@ -227,9 +233,10 @@ export class Users {
   }
 
   /**
-   * Returns user email addresses for a set of accountIds. This API is only available to apps approved by Atlassian,
-   * according to these
+   * Returns a user's email address regardless of the user’s profile visibility settings. For Connect apps, this API is
+   * only available to apps approved by Atlassian, according to these
    * [guidelines](https://community.developer.atlassian.com/t/guidelines-for-requesting-access-to-email-address/27603).
+   * For Forge apps, this API only supports access via asApp() requests.
    *
    * Any accounts which are not available will not be included in the result.
    *
@@ -241,9 +248,10 @@ export class Users {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Returns user email addresses for a set of accountIds. This API is only available to apps approved by Atlassian,
-   * according to these
+   * Returns a user's email address regardless of the user’s profile visibility settings. For Connect apps, this API is
+   * only available to apps approved by Atlassian, according to these
    * [guidelines](https://community.developer.atlassian.com/t/guidelines-for-requesting-access-to-email-address/27603).
+   * For Forge apps, this API only supports access via asApp() requests.
    *
    * Any accounts which are not available will not be included in the result.
    *
@@ -275,6 +283,8 @@ export class Users {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'Confluence Administrator' global permission
    * if specifying a user, otherwise permission to access the Confluence site ('Can use' global permission).
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getBulkUserMigration<T = Models.MigratedUserArray>(
     parameters: Parameters.GetBulkUserMigration,
@@ -286,6 +296,8 @@ export class Users {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'Confluence Administrator' global permission
    * if specifying a user, otherwise permission to access the Confluence site ('Can use' global permission).
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getBulkUserMigration<T = Models.MigratedUserArray>(
     parameters: Parameters.GetBulkUserMigration,

package/src/clients/baseClient.ts

@@ -4,16 +4,15 @@ import axios from 'axios';
 import { getAuthenticationToken } from '~/services';
 import type { Callback } from '~/callback';
 import type { Client } from './client';
-import {
-  ConfigSchema,
-  type Config,
-  type Error as ConfluenceError,
-} from '~/config';
+import { ConfigSchema, type Config, type Error as ConfluenceError } from '~/config';
 import type { RequestConfig } from '~/requestConfig';
-import { ZodError } from 'zod';
+import { ZodError, z } from 'zod';
 
 const ATLASSIAN_TOKEN_CHECK_FLAG = 'X-Atlassian-Token';
 const ATLASSIAN_TOKEN_CHECK_NOCHECK_VALUE = 'no-check';
+const NON_EMAIL_BASIC_AUTH_WARNING =
+  '[confluence.js] authentication.basic.email is not a valid email address; treating it as login workaround.';
+const EMAIL_SCHEMA = z.email();
 
 export class BaseClient implements Client {
   #instance: AxiosInstance | undefined;
@@ -23,15 +22,32 @@ export class BaseClient implements Client {
 
     try {
       this.config = ConfigSchema.parse(this.config);
+      this.warnIfNonEmailBasicAuthLogin();
     } catch (e) {
-      if (e instanceof ZodError && e.errors[0].code === 'invalid_string') {
-        throw new Error(e.errors[0].message);
+      if (e instanceof ZodError && e.issues[0]?.message) {
+        throw new Error(e.issues[0].message, e);
       }
 
       throw e;
     }
   }
 
+  private warnIfNonEmailBasicAuthLogin() {
+    if (this.config.suppressWarnings) {
+      return;
+    }
+
+    const authentication = this.config.authentication;
+
+    if (!authentication || !('basic' in authentication)) {
+      return;
+    }
+
+    if (!EMAIL_SCHEMA.safeParse(authentication.basic.email).success) {
+      console.warn(NON_EMAIL_BASIC_AUTH_WARNING);
+    }
+  }
+
   protected paramSerializer(parameters: Record<string, any>): string {
     const parts: string[] = [];
 

package/src/clients/confluenceClient.ts

@@ -32,6 +32,7 @@ import {
   Template,
   Themes,
   Users,
+  UserProperties,
 } from '../api';
 
 export class ConfluenceClient extends BaseClient {
@@ -48,10 +49,12 @@ export class ConfluenceClient extends BaseClient {
   contentAttachments = new ContentAttachments(this);
   contentBody = new ContentBody(this);
   contentChildrenAndDescendants = new ContentChildrenAndDescendants(this);
+  /** @deprecated Will be removed in next major version. */
   contentComments = new ContentComments(this);
   contentLabels = new ContentLabels(this);
   contentMacroBody = new ContentMacroBody(this);
   contentPermissions = new ContentPermissions(this);
+  /** @deprecated Will be removed in next major version. */
   contentProperties = new ContentProperties(this);
   contentRestrictions = new ContentRestrictions(this);
   contentStates = new ContentStates(this);
@@ -60,6 +63,7 @@ export class ConfluenceClient extends BaseClient {
   dynamicModules = new DynamicModules(this);
   experimental = new Experimental(this);
   group = new Group(this);
+  /** @deprecated Will be removed in next major version. */
   inlineTasks = new InlineTasks(this);
   labelInfo = new LabelInfo(this);
   longRunningTask = new LongRunningTask(this);
@@ -68,9 +72,11 @@ export class ConfluenceClient extends BaseClient {
   settings = new Settings(this);
   space = new Space(this);
   spacePermissions = new SpacePermissions(this);
+  /** @deprecated Will be removed in next major version. */
   spaceProperties = new SpaceProperties(this);
   spaceSettings = new SpaceSettings(this);
   template = new Template(this);
   themes = new Themes(this);
   users = new Users(this);
+  userProperties = new UserProperties(this);
 }

package/src/config.ts

@@ -9,7 +9,7 @@ import type { AxiosError } from 'axios';
 export const BasicSchema = z.strictObject({
   basic: z.strictObject({
     /** User's email associated with Atlassian account */
-    email: z.string().email(),
+    email: z.string(),
     /**
      * API token generated from Atlassian account settings
      *
@@ -48,18 +48,22 @@ export const RequestConfigSchema = z.any();
 /** Middleware configuration schema */
 export const MiddlewaresSchema = z.object({
   /** Error handler middleware */
-  onError: z.optional(z.function().args(z.any()).returns(z.void())),
+  onError: z.optional(z.custom<(input: unknown) => void>((value) => typeof value === 'function')),
   /** Response handler middleware */
-  onResponse: z.optional(z.function().args(z.any()).returns(z.void())),
+  onResponse: z.optional(z.custom<(input: unknown) => void>((value) => typeof value === 'function')),
 });
 
 export const ConfigSchema = z.object({
-  host: z.string().url({ message:  'Couldn\'t parse the host URL. Perhaps you forgot to add \'http://\' or \'https://\' at the beginning of the URL?' }),
+  host: z.url({
+    error:
+      'Couldn\'t parse the host URL. Perhaps you forgot to add \'http://\' or \'https://\' at the beginning of the URL?',
+  }),
   baseRequestConfig: z.optional(RequestConfigSchema),
   authentication: z.optional(AuthenticationSchema),
   middlewares: z.optional(MiddlewaresSchema),
   /** Adds `'X-Atlassian-Token': 'no-check'` to each request header */
   noCheckAtlassianToken: z.optional(z.boolean()),
+  suppressWarnings: z.boolean().optional().default(false),
   /** Prefix for all API routes. */
   apiPrefix: z.optional(z.string()),
 });

package/src/services/authenticationService/authentications/createJWTAuthentication.ts

@@ -1,4 +1,4 @@
-import * as jwt from 'atlassian-jwt';
+import * as jwt from '@atlassian/atlassian-jwt';
 import type { JWT } from '~';
 
 export function createJWTAuthentication(

package/favicon.svg

@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72">
-  <g style="" transform="matrix(1, 0, 0, 1, -214, -214.000031)">
-    <path class="st0"
-          d="M 231.14 281.76 C 226.01 279.28 222.08 275.78 219.33 271.27 C 216.59 266.76 215.21 261.57 215.21 255.69 C 215.21 247.92 216.99 240.91 220.55 234.67 C 224.11 228.43 229.13 223.52 235.59 219.92 C 242.06 216.33 249.47 214.53 257.84 214.53 C 263.98 214.53 269.4 215.58 274.11 217.67 C 278.81 219.76 282.37 222.77 284.79 226.69 L 273.32 236.1 C 269.66 230.74 264.14 228.06 256.76 228.06 C 251.73 228.06 247.29 229.24 243.43 231.59 C 239.57 233.94 236.59 237.14 234.46 241.19 C 232.34 245.24 231.27 249.75 231.27 254.71 C 231.27 260 232.95 264.2 236.32 267.3 C 239.68 270.4 244.4 271.95 250.48 271.95 C 257.73 271.95 263.81 269.3 268.71 264.01 L 278.12 273.61 C 271.32 281.52 261.66 285.47 249.11 285.47 C 242.26 285.48 236.27 284.24 231.14 281.76 Z"
-          style="fill: rgb(42, 86, 163); stroke-width: 1;"></path>
-  </g>
-</svg>