Document Instance API

Author: alexisintech

.typedoc/__tests__/file-structure.test.ts

@@ -64,6 +64,8 @@ describe('Typedoc output', () => {
         "backend/email-address-api/methods",
         "backend/enterprise-connection-api",
         "backend/enterprise-connection-api/methods",
+        "backend/instance-api",
+        "backend/instance-api/methods",
         "backend/invitation-api",
         "backend/invitation-api/methods",
         "backend/m2-m-token-api",

.typedoc/reference-objects.mjs

@@ -140,6 +140,10 @@ export const BACKEND_API_CONFIG = {
     symbol: 'APIKeysAPI',
     declarationHint: 'api/endpoints/APIKeysApi',
   },
+  'backend/instance-api/instance-api.mdx': {
+    symbol: 'InstanceAPI',
+    declarationHint: 'api/endpoints/InstanceApi',
+  },
 };
 
 /** Stable iteration order matches key order in {@link REFERENCE_OBJECT_CONFIG} then {@link BACKEND_API_CONFIG}. */

packages/backend/src/api/endpoints/InstanceApi.ts

@@ -6,81 +6,75 @@ import { AbstractAPI } from './AbstractApi';
 
 const basePath = '/instance';
 
-type UpdateParams = {
-  /**
-   * Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.
-   *
-   * @remarks Defaults to true for development instances.
-   */
+/** @generateWithEmptyComment */
+export type UpdateParams = {
+  /** Toggles [test mode](https://clerk.com/docs/guides/development/testing/test-emails-and-phones#set-up-test-mode) for this instance, allowing the use of test email addresses and phone numbers. Defaults to `true` for development instances. */
   testMode?: boolean | null | undefined;
-  /**
-   * Whether the instance should be using the HIBP service to check passwords for breaches
-   */
+  /** Whether the instance should be using the Have I Been Pwned (HIBP) service to check passwords for breaches. */
   hibp?: boolean | null | undefined;
-  /**
-   * The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain.
-   *
-   * @remarks This can be helpful if you do not have a high domain reputation.
-   */
+  /** Whether the instance should send emails from "verifications@clerk.dev" instead of your domain. This can be helpful if you do not have a high domain reputation. */
   enhancedEmailDeliverability?: boolean | null | undefined;
+  /** The support email for the instance. */
   supportEmail?: string | null | undefined;
+  /** The npm version for `@clerk/clerk-js`. */
   clerkJsVersion?: string | null | undefined;
+  /** The development origin for the instance. */
   developmentOrigin?: string | null | undefined;
-  /**
-   * For browser-like stacks such as browser extensions, Electron, or Capacitor.js the instance allowed origins need to be updated with the request origin value.
-   *
-   * @remarks For Chrome extensions popup, background, or service worker pages the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost.
-   */
+  /** For browser-like stacks such as browser extensions, Electron, or Capacitor.js, the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages the origin is `chrome-extension://extension_uiid`. For Electron apps the default origin is `http://localhost:3000`. For Capacitor.js, the origin is `capacitor://localhost`. */
   allowedOrigins?: Array<string> | undefined;
-  /**
-   * Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies).
-   */
+  /** Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). */
   urlBasedSessionSyncing?: boolean | null | undefined;
-  /**
-   * Overrides the sign-in strategy that is preferred when a password is required.
-   *
-   * @remarks Accepts `'password'` or `'otp'`. Pass an empty string to clear the override. Passing `null` or `undefined` leaves the current value unchanged. The value is only consulted when a password is required, and is dormant otherwise.
-   */
+  /** Overrides the sign-in strategy that is preferred when a password is required. The value is only consulted when a password is required, and is dormant otherwise. Pass an empty string to clear the override. Passing `null` or `undefined` leaves the current value unchanged. */
   preferredSignInStrategyWhenPasswordRequired?: 'password' | 'otp' | '' | null | undefined;
 };
 
-type UpdateRestrictionsParams = {
+/** @generateWithEmptyComment */
+export type UpdateRestrictionsParams = {
+  /** Whether the instance should have [**Allowlist**](https://clerk.com/docs/guides/secure/restricting-access#allowlist) enabled. */
   allowlist?: boolean | null | undefined;
+  /** Whether the instance should have [**Blocklist**](https://clerk.com/docs/guides/secure/restricting-access#blocklist) enabled. */
   blocklist?: boolean | null | undefined;
+  /** Whether the instance should have [**Block email subaddresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */
   blockEmailSubaddresses?: boolean | null | undefined;
+  /** Whether the instance should have [**Block sign-ups that use disposable email domains**](https://clerk.com/docs/guides/secure/restricting-access#block-sign-ups-that-use-disposable-email-addresses) enabled. */
   blockDisposableEmailDomains?: boolean | null | undefined;
+  /** Whether the instance should [ignore dots for Gmail addresses](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses). */
   ignoreDotsForGmailAddresses?: boolean | null | undefined;
 };
 
-type UpdateOrganizationSettingsParams = {
+/** @generateWithEmptyComment */
+export type UpdateOrganizationSettingsParams = {
+  /** Whether the instance should enable [Organizations](https://clerk.com/docs/guides/organizations/overview). */
   enabled?: boolean | null | undefined;
+  /** The maximum number of [memberships allowed](https://clerk.com/docs/guides/organizations/configure#membership-limits) per Organization. */
   maxAllowedMemberships?: number | null | undefined;
+  /** Whether [Organization admins](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) are allowed to delete Organizations. */
   adminDeleteEnabled?: boolean | null | undefined;
+  /** Whether [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) are enabled for Organizations. */
   domainsEnabled?: boolean | null | undefined;
-  /**
-   * Specifies which [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) to enable for your Organization Domains.
-   *
-   * @remarks Supported modes are 'automatic_invitation' & 'automatic_suggestion'.
-   */
+  /** Specifies which [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) to enable for your Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Supported modes are `'automatic_invitation'` & `'automatic_suggestion'`. */
   domainsEnrollmentModes?: Array<string> | undefined;
-  /**
-   * Specifies what the default Organization Role is for an Organization creator.
-   */
+  /** Specifies what the default Organization [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) is for an Organization creator. */
   creatorRoleId?: string | null | undefined;
-  /**
-   * Specifies what the default Organization Role is for the Organization Domains.
-   */
+  /** Specifies what the default Organization [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) is for the Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). */
   domainsDefaultRoleId?: string | null | undefined;
 };
 
+/** @generateWithEmptyComment */
 export class InstanceAPI extends AbstractAPI {
+  /**
+   * Gets the current [`Instance`](https://clerk.com/docs/reference/backend/types/backend-instance).
+   */
   public async get() {
     return this.request<Instance>({
       method: 'GET',
       path: basePath,
     });
   }
 
+  /**
+   * Updates the current instance.
+   */
   public async update(params: UpdateParams) {
     return this.request<void>({
       method: 'PATCH',
@@ -89,6 +83,10 @@ export class InstanceAPI extends AbstractAPI {
     });
   }
 
+  /**
+   * Updates the [restriction](https://clerk.com/docs/guides/secure/restricting-access) settings for the current instance.
+   * @returns The updated [`InstanceRestrictions`](https://clerk.com/docs/reference/backend/types/backend-instance-restrictions).
+   */
   public async updateRestrictions(params: UpdateRestrictionsParams) {
     return this.request<InstanceRestrictions>({
       method: 'PATCH',
@@ -97,13 +95,20 @@ export class InstanceAPI extends AbstractAPI {
     });
   }
 
+  /**
+   * Gets the [`OrganizationSettings`](https://clerk.com/docs/reference/backend/types/backend-organization-settings) for the current instance.
+   */
   public async getOrganizationSettings() {
     return this.request<OrganizationSettings>({
       method: 'GET',
       path: joinPaths(basePath, 'organization_settings'),
     });
   }
 
+  /**
+   * Updates the [Organization-related settings](https://clerk.com/docs/guides/organizations/configure) for the current instance.
+   * @returns The updated [`OrganizationSettings`](https://clerk.com/docs/reference/backend/types/backend-organization-settings).
+   */
   public async updateOrganizationSettings(params: UpdateOrganizationSettingsParams) {
     return this.request<OrganizationSettings>({
       method: 'PATCH',

packages/backend/src/api/resources/Instance.ts

@@ -1,9 +1,13 @@
 import type { InstanceJSON } from './JSON';
 
+/** @generateWithEmptyComment */
 export class Instance {
   constructor(
+    /** The unique identifier for the instance. */
     readonly id: string,
+    /** The type of instance environment, either `'production'` or `'development'`. */
     readonly environmentType: string,
+    /** For browser-like stacks such as browser extensions, Electron, or Capacitor.js, the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages the origin is `chrome-extension://extension_uiid`. For Electron apps the default origin is `http://localhost:3000`. For Capacitor.js, the origin is `capacitor://localhost`. */
     readonly allowedOrigins: Array<string> | null,
   ) {}
 

packages/backend/src/api/resources/InstanceRestrictions.ts

@@ -1,11 +1,17 @@
 import type { InstanceRestrictionsJSON } from './JSON';
 
+/** The `InstanceRestrictions` object represents the [restrictions](https://clerk.com/docs/guides/secure/restricting-access) settings for the current instance. */
 export class InstanceRestrictions {
   constructor(
+    /** Whether the instance has [**Allowlist**](https://clerk.com/docs/guides/secure/restricting-access#allowlist) enabled. */
     readonly allowlist: boolean,
+    /** Whether the instance has [**Blocklist**](https://clerk.com/docs/guides/secure/restricting-access#blocklist) enabled. */
     readonly blocklist: boolean,
+    /** Whether the instance has [**Block email subaddresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */
     readonly blockEmailSubaddresses: boolean,
+    /** Whether the instance has [**Block sign-ups that use disposable email domains**](https://clerk.com/docs/guides/secure/restricting-access#block-sign-ups-that-use-disposable-email-addresses) enabled. */
     readonly blockDisposableEmailDomains: boolean,
+    /** Whether the instance has [**Ignore dots for Gmail addresses**](https://clerk.com/docs/guides/secure/restricting-access#block-email-subaddresses) enabled. */
     readonly ignoreDotsForGmailAddresses: boolean,
   ) {}
 

packages/backend/src/api/resources/OrganizationSettings.ts

@@ -1,17 +1,36 @@
 import type { DomainsEnrollmentModes } from './Enums';
 import type { OrganizationSettingsJSON } from './JSON';
 
+/** The `OrganizationSettings` object represents the [Organization-related settings](https://clerk.com/docs/guides/organizations/configure) for the current instance. */
 export class OrganizationSettings {
   constructor(
+    /** Whether the instance has [Organizations](https://clerk.com/docs/guides/organizations/overview) enabled. */
     readonly enabled: boolean,
+    /** The maximum number of [memberships allowed](https://clerk.com/docs/guides/organizations/configure#membership-limits) per Organization. */
     readonly maxAllowedMemberships: number,
+    /** The maximum number of [Roles allowed](https://clerk.com/docs/guides/organizations/configure#role-limits) per Organization. */
     readonly maxAllowedRoles: number,
+    /** The maximum number of [Permissions allowed](https://clerk.com/docs/guides/organizations/configure#permission-limits) per Organization. */
     readonly maxAllowedPermissions: number,
+    /** The default [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) for an Organization creator. */
     readonly creatorRole: string,
+    /** Whether [admins](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) are allowed to delete Organizations. */
     readonly adminDeleteEnabled: boolean,
+    /** Whether the instance has [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) enabled. */
     readonly domainsEnabled: boolean,
+    /** Whether the instance has [Organization slugs](https://clerk.com/docs/guides/organizations/add-members/verified-domains#organization-slugs) disabled. */
     readonly slugDisabled: boolean,
+    /**
+     * The [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) available for Verified Domains.
+     *
+     * <ul>
+     *  <li>`manual_invitation`: No automatic enrollment. Users with a matching email domain are not given any [invitation](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-invitations) or [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions); an [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions#default-roles) must invite them manually.</li>
+     *  <li>`automatic_invitation`: Users with a matching email domain automatically receive a pending [invitation](https://clerk.com/docs/reference/types/organization-invitation) (assigned the Organization's default Role) which they can accept to join.</li>
+     *  <li>`automatic_suggestion`: Users with a matching email domain automatically receive a [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions) to join, which they can request.</li>
+     * </ul>
+     */
     readonly domainsEnrollmentModes: Array<DomainsEnrollmentModes>,
+    /** The default [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) for the Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). */
     readonly domainsDefaultRole: string,
   ) {}