@logto/js 2.1.2 → 3.0.0

package/README.md

@@ -5,8 +5,6 @@
 
 The Logto JavaScript Core SDK written in TypeScript. Check out our [docs](https://docs.logto.io/JavaScript/js/) for more information.
 
-We also provide [文档](https://docs.logto.io/zh-cn/sdk/JavaScript/js/) in Simplified Chinese.
-
 ## Installation
 
 ### Using npm

package/lib/consts/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var openid = require('./openid.cjs');
+
 const ContentType = {
     formUrlEncoded: { 'Content-Type': 'application/x-www-form-urlencoded' },
 };
@@ -31,6 +33,8 @@ exports.QueryKey = void 0;
     QueryKey["Token"] = "token";
     // Need to align with the OIDC extraParams settings in core
     QueryKey["InteractionMode"] = "interaction_mode";
+    /** The query key for specifying the organization ID. */
+    QueryKey["OrganizationId"] = "organization_id";
 })(exports.QueryKey || (exports.QueryKey = {}));
 /** The prompt parameter to be used for the authorization request. */
 exports.Prompt = void 0;
@@ -47,47 +51,23 @@ exports.Prompt = void 0;
      */
     Prompt["Login"] = "login";
 })(exports.Prompt || (exports.Prompt = {}));
-// TODO: @sijie @charles find a proper way to sync scopes constants with core
-exports.ReservedScope = void 0;
-(function (ReservedScope) {
-    ReservedScope["OpenId"] = "openid";
-    ReservedScope["OfflineAccess"] = "offline_access";
-})(exports.ReservedScope || (exports.ReservedScope = {}));
-/**
- * Scopes for ID Token and Userinfo Endpoint.
- */
-exports.UserScope = void 0;
-(function (UserScope) {
-    /**
-     * Scope for basic user info.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Profile"] = "profile";
-    /**
-     * Scope for user email address.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Email"] = "email";
-    /**
-     * Scope for user phone number.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Phone"] = "phone";
-    /**
-     * Scope for user's custom data.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["CustomData"] = "custom_data";
-    /**
-     * Scope for user's social identity details.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Identities"] = "identities";
-})(exports.UserScope || (exports.UserScope = {}));
 
+Object.defineProperty(exports, 'ReservedResource', {
+    enumerable: true,
+    get: function () { return openid.ReservedResource; }
+});
+Object.defineProperty(exports, 'ReservedScope', {
+    enumerable: true,
+    get: function () { return openid.ReservedScope; }
+});
+Object.defineProperty(exports, 'UserScope', {
+    enumerable: true,
+    get: function () { return openid.UserScope; }
+});
+exports.buildOrganizationUrn = openid.buildOrganizationUrn;
+exports.getOrganizationIdFromUrn = openid.getOrganizationIdFromUrn;
+exports.idTokenClaims = openid.idTokenClaims;
+exports.organizationUrnPrefix = openid.organizationUrnPrefix;
+exports.userClaims = openid.userClaims;
+exports.userinfoClaims = openid.userinfoClaims;
 exports.ContentType = ContentType;

package/lib/consts/index.d.ts

@@ -1,3 +1,4 @@
+export * from './openid.js';
 export declare const ContentType: {
     formUrlEncoded: {
         'Content-Type': string;
@@ -27,7 +28,9 @@ export declare enum QueryKey {
     Scope = "scope",
     State = "state",
     Token = "token",
-    InteractionMode = "interaction_mode"
+    InteractionMode = "interaction_mode",
+    /** The query key for specifying the organization ID. */
+    OrganizationId = "organization_id"
 }
 /** The prompt parameter to be used for the authorization request. */
 export declare enum Prompt {
@@ -43,42 +46,3 @@ export declare enum Prompt {
      */
     Login = "login"
 }
-export declare enum ReservedScope {
-    OpenId = "openid",
-    OfflineAccess = "offline_access"
-}
-/**
- * Scopes for ID Token and Userinfo Endpoint.
- */
-export declare enum UserScope {
-    /**
-     * Scope for basic user info.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    Profile = "profile",
-    /**
-     * Scope for user email address.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    Email = "email",
-    /**
-     * Scope for user phone number.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    Phone = "phone",
-    /**
-     * Scope for user's custom data.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    CustomData = "custom_data",
-    /**
-     * Scope for user's social identity details.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    Identities = "identities"
-}

package/lib/consts/index.js

@@ -1,3 +1,5 @@
+export { ReservedResource, ReservedScope, UserScope, buildOrganizationUrn, getOrganizationIdFromUrn, idTokenClaims, organizationUrnPrefix, userClaims, userinfoClaims } from './openid.js';
+
 const ContentType = {
     formUrlEncoded: { 'Content-Type': 'application/x-www-form-urlencoded' },
 };
@@ -29,6 +31,8 @@ var QueryKey;
     QueryKey["Token"] = "token";
     // Need to align with the OIDC extraParams settings in core
     QueryKey["InteractionMode"] = "interaction_mode";
+    /** The query key for specifying the organization ID. */
+    QueryKey["OrganizationId"] = "organization_id";
 })(QueryKey || (QueryKey = {}));
 /** The prompt parameter to be used for the authorization request. */
 var Prompt;
@@ -45,47 +49,5 @@ var Prompt;
      */
     Prompt["Login"] = "login";
 })(Prompt || (Prompt = {}));
-// TODO: @sijie @charles find a proper way to sync scopes constants with core
-var ReservedScope;
-(function (ReservedScope) {
-    ReservedScope["OpenId"] = "openid";
-    ReservedScope["OfflineAccess"] = "offline_access";
-})(ReservedScope || (ReservedScope = {}));
-/**
- * Scopes for ID Token and Userinfo Endpoint.
- */
-var UserScope;
-(function (UserScope) {
-    /**
-     * Scope for basic user info.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Profile"] = "profile";
-    /**
-     * Scope for user email address.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Email"] = "email";
-    /**
-     * Scope for user phone number.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Phone"] = "phone";
-    /**
-     * Scope for user's custom data.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["CustomData"] = "custom_data";
-    /**
-     * Scope for user's social identity details.
-     *
-     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
-     */
-    UserScope["Identities"] = "identities";
-})(UserScope || (UserScope = {}));
 
-export { ContentType, Prompt, QueryKey, ReservedScope, TokenGrantType, UserScope };
+export { ContentType, Prompt, QueryKey, TokenGrantType };

package/lib/consts/openid.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * @overview Constants for Logto. Synchronized with `@logto/core-kit` package at hash `081094d`.
+ */
+/** Scopes that reserved by Logto, which will be added to the auth request automatically. */
+exports.ReservedScope = void 0;
+(function (ReservedScope) {
+    ReservedScope["OpenId"] = "openid";
+    ReservedScope["OfflineAccess"] = "offline_access";
+})(exports.ReservedScope || (exports.ReservedScope = {}));
+/** Resources that reserved by Logto, which cannot be defined by users. */
+exports.ReservedResource = void 0;
+(function (ReservedResource) {
+    /**
+     * The resource for organization template per RFC 0001.
+     *
+     * @see {@link https://github.com/logto-io/rfcs | RFC 0001} for more details.
+     */
+    ReservedResource["Organization"] = "urn:logto:resource:organizations";
+})(exports.ReservedResource || (exports.ReservedResource = {}));
+/**
+ * Scopes for ID Token and Userinfo Endpoint.
+ */
+exports.UserScope = void 0;
+(function (UserScope) {
+    /**
+     * Scope for basic user info.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Profile"] = "profile";
+    /**
+     * Scope for user email address.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Email"] = "email";
+    /**
+     * Scope for user phone number.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Phone"] = "phone";
+    /**
+     * Scope for user's custom data.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["CustomData"] = "custom_data";
+    /**
+     * Scope for user's social identity details.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Identities"] = "identities";
+    /**
+     * Scope for user's roles.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Roles"] = "roles";
+    /**
+     * Scope for user's organization IDs and perform organization token grant per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Organizations"] = "urn:logto:scope:organizations";
+    /**
+     * Scope for user's organization roles per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["OrganizationRoles"] = "urn:logto:scope:organization_roles";
+})(exports.UserScope || (exports.UserScope = {}));
+/**
+ * Mapped claims that ID Token includes.
+ */
+const idTokenClaims = Object.freeze({
+    [exports.UserScope.Profile]: ['name', 'picture', 'username'],
+    [exports.UserScope.Email]: ['email', 'email_verified'],
+    [exports.UserScope.Phone]: ['phone_number', 'phone_number_verified'],
+    [exports.UserScope.Roles]: ['roles'],
+    [exports.UserScope.Organizations]: ['organizations'],
+    [exports.UserScope.OrganizationRoles]: ['organization_roles'],
+    [exports.UserScope.CustomData]: [],
+    [exports.UserScope.Identities]: [],
+});
+/**
+ * Additional claims that Userinfo Endpoint returns.
+ */
+const userinfoClaims = Object.freeze({
+    [exports.UserScope.Profile]: [],
+    [exports.UserScope.Email]: [],
+    [exports.UserScope.Phone]: [],
+    [exports.UserScope.Roles]: [],
+    [exports.UserScope.Organizations]: [],
+    [exports.UserScope.OrganizationRoles]: [],
+    [exports.UserScope.CustomData]: ['custom_data'],
+    [exports.UserScope.Identities]: ['identities'],
+});
+const userClaims = Object.freeze(
+// Hard to infer type directly, use `as` for a workaround.
+// eslint-disable-next-line no-restricted-syntax
+Object.fromEntries(Object.values(exports.UserScope).map((current) => [
+    current,
+    [...idTokenClaims[current], ...userinfoClaims[current]],
+])));
+/**
+ * The prefix of the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @example
+ * ```
+ * urn:logto:organization:123 // organization with ID 123
+ * ```
+ * @see {@link https://en.wikipedia.org/wiki/Uniform_Resource_Name | Uniform Resource Name}
+ */
+const organizationUrnPrefix = 'urn:logto:organization:';
+/**
+ * Build the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param organizationId The ID of the organization.
+ * @returns The URN for the organization.
+ * @see {@link organizationUrnPrefix} for the prefix of the URN.
+ * @example
+ * ```ts
+ * buildOrganizationUrn('1') // returns 'urn:logto:organization:1'
+ * ```
+ */
+const buildOrganizationUrn = (organizationId) => `${organizationUrnPrefix}${organizationId}`;
+/**
+ * Get the organization ID from the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param urn The URN for the organization. Must start with {@link organizationUrnPrefix}.
+ * @returns The ID of the organization.
+ * @throws {TypeError} If the URN is invalid.
+ * @example
+ * ```ts
+ * getOrganizationIdFromUrn('1') // throws TypeError
+ * getOrganizationIdFromUrn('urn:logto:organization:1') // returns '1'
+ * ```
+ */
+const getOrganizationIdFromUrn = (urn) => {
+    if (!urn.startsWith(organizationUrnPrefix)) {
+        throw new TypeError('Invalid organization URN.');
+    }
+    return urn.slice(organizationUrnPrefix.length);
+};
+
+exports.buildOrganizationUrn = buildOrganizationUrn;
+exports.getOrganizationIdFromUrn = getOrganizationIdFromUrn;
+exports.idTokenClaims = idTokenClaims;
+exports.organizationUrnPrefix = organizationUrnPrefix;
+exports.userClaims = userClaims;
+exports.userinfoClaims = userinfoClaims;

package/lib/consts/openid.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @overview Constants for Logto. Synchronized with `@logto/core-kit` package at hash `081094d`.
+ */
+/** Scopes that reserved by Logto, which will be added to the auth request automatically. */
+export declare enum ReservedScope {
+    OpenId = "openid",
+    OfflineAccess = "offline_access"
+}
+/** Resources that reserved by Logto, which cannot be defined by users. */
+export declare enum ReservedResource {
+    /**
+     * The resource for organization template per RFC 0001.
+     *
+     * @see {@link https://github.com/logto-io/rfcs | RFC 0001} for more details.
+     */
+    Organization = "urn:logto:resource:organizations"
+}
+export type UserClaim = 'name' | 'picture' | 'username' | 'email' | 'email_verified' | 'phone_number' | 'phone_number_verified' | 'roles' | 'organizations' | 'organization_roles' | 'custom_data' | 'identities';
+/**
+ * Scopes for ID Token and Userinfo Endpoint.
+ */
+export declare enum UserScope {
+    /**
+     * Scope for basic user info.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Profile = "profile",
+    /**
+     * Scope for user email address.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Email = "email",
+    /**
+     * Scope for user phone number.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Phone = "phone",
+    /**
+     * Scope for user's custom data.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    CustomData = "custom_data",
+    /**
+     * Scope for user's social identity details.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Identities = "identities",
+    /**
+     * Scope for user's roles.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Roles = "roles",
+    /**
+     * Scope for user's organization IDs and perform organization token grant per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    Organizations = "urn:logto:scope:organizations",
+    /**
+     * Scope for user's organization roles per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    OrganizationRoles = "urn:logto:scope:organization_roles"
+}
+/**
+ * Mapped claims that ID Token includes.
+ */
+export declare const idTokenClaims: Readonly<Record<UserScope, UserClaim[]>>;
+/**
+ * Additional claims that Userinfo Endpoint returns.
+ */
+export declare const userinfoClaims: Readonly<Record<UserScope, UserClaim[]>>;
+export declare const userClaims: Readonly<Record<UserScope, UserClaim[]>>;
+/**
+ * The prefix of the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @example
+ * ```
+ * urn:logto:organization:123 // organization with ID 123
+ * ```
+ * @see {@link https://en.wikipedia.org/wiki/Uniform_Resource_Name | Uniform Resource Name}
+ */
+export declare const organizationUrnPrefix = "urn:logto:organization:";
+/**
+ * Build the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param organizationId The ID of the organization.
+ * @returns The URN for the organization.
+ * @see {@link organizationUrnPrefix} for the prefix of the URN.
+ * @example
+ * ```ts
+ * buildOrganizationUrn('1') // returns 'urn:logto:organization:1'
+ * ```
+ */
+export declare const buildOrganizationUrn: (organizationId: string) => string;
+/**
+ * Get the organization ID from the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param urn The URN for the organization. Must start with {@link organizationUrnPrefix}.
+ * @returns The ID of the organization.
+ * @throws {TypeError} If the URN is invalid.
+ * @example
+ * ```ts
+ * getOrganizationIdFromUrn('1') // throws TypeError
+ * getOrganizationIdFromUrn('urn:logto:organization:1') // returns '1'
+ * ```
+ */
+export declare const getOrganizationIdFromUrn: (urn: string) => string;

package/lib/consts/openid.js

@@ -0,0 +1,148 @@
+/**
+ * @overview Constants for Logto. Synchronized with `@logto/core-kit` package at hash `081094d`.
+ */
+/** Scopes that reserved by Logto, which will be added to the auth request automatically. */
+var ReservedScope;
+(function (ReservedScope) {
+    ReservedScope["OpenId"] = "openid";
+    ReservedScope["OfflineAccess"] = "offline_access";
+})(ReservedScope || (ReservedScope = {}));
+/** Resources that reserved by Logto, which cannot be defined by users. */
+var ReservedResource;
+(function (ReservedResource) {
+    /**
+     * The resource for organization template per RFC 0001.
+     *
+     * @see {@link https://github.com/logto-io/rfcs | RFC 0001} for more details.
+     */
+    ReservedResource["Organization"] = "urn:logto:resource:organizations";
+})(ReservedResource || (ReservedResource = {}));
+/**
+ * Scopes for ID Token and Userinfo Endpoint.
+ */
+var UserScope;
+(function (UserScope) {
+    /**
+     * Scope for basic user info.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Profile"] = "profile";
+    /**
+     * Scope for user email address.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Email"] = "email";
+    /**
+     * Scope for user phone number.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Phone"] = "phone";
+    /**
+     * Scope for user's custom data.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["CustomData"] = "custom_data";
+    /**
+     * Scope for user's social identity details.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Identities"] = "identities";
+    /**
+     * Scope for user's roles.
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Roles"] = "roles";
+    /**
+     * Scope for user's organization IDs and perform organization token grant per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["Organizations"] = "urn:logto:scope:organizations";
+    /**
+     * Scope for user's organization roles per [RFC 0001](https://github.com/logto-io/rfcs).
+     *
+     * See {@link idTokenClaims} for mapped claims in ID Token and {@link userinfoClaims} for additional claims in Userinfo Endpoint.
+     */
+    UserScope["OrganizationRoles"] = "urn:logto:scope:organization_roles";
+})(UserScope || (UserScope = {}));
+/**
+ * Mapped claims that ID Token includes.
+ */
+const idTokenClaims = Object.freeze({
+    [UserScope.Profile]: ['name', 'picture', 'username'],
+    [UserScope.Email]: ['email', 'email_verified'],
+    [UserScope.Phone]: ['phone_number', 'phone_number_verified'],
+    [UserScope.Roles]: ['roles'],
+    [UserScope.Organizations]: ['organizations'],
+    [UserScope.OrganizationRoles]: ['organization_roles'],
+    [UserScope.CustomData]: [],
+    [UserScope.Identities]: [],
+});
+/**
+ * Additional claims that Userinfo Endpoint returns.
+ */
+const userinfoClaims = Object.freeze({
+    [UserScope.Profile]: [],
+    [UserScope.Email]: [],
+    [UserScope.Phone]: [],
+    [UserScope.Roles]: [],
+    [UserScope.Organizations]: [],
+    [UserScope.OrganizationRoles]: [],
+    [UserScope.CustomData]: ['custom_data'],
+    [UserScope.Identities]: ['identities'],
+});
+const userClaims = Object.freeze(
+// Hard to infer type directly, use `as` for a workaround.
+// eslint-disable-next-line no-restricted-syntax
+Object.fromEntries(Object.values(UserScope).map((current) => [
+    current,
+    [...idTokenClaims[current], ...userinfoClaims[current]],
+])));
+/**
+ * The prefix of the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @example
+ * ```
+ * urn:logto:organization:123 // organization with ID 123
+ * ```
+ * @see {@link https://en.wikipedia.org/wiki/Uniform_Resource_Name | Uniform Resource Name}
+ */
+const organizationUrnPrefix = 'urn:logto:organization:';
+/**
+ * Build the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param organizationId The ID of the organization.
+ * @returns The URN for the organization.
+ * @see {@link organizationUrnPrefix} for the prefix of the URN.
+ * @example
+ * ```ts
+ * buildOrganizationUrn('1') // returns 'urn:logto:organization:1'
+ * ```
+ */
+const buildOrganizationUrn = (organizationId) => `${organizationUrnPrefix}${organizationId}`;
+/**
+ * Get the organization ID from the URN (Uniform Resource Name) for the organization in Logto.
+ *
+ * @param urn The URN for the organization. Must start with {@link organizationUrnPrefix}.
+ * @returns The ID of the organization.
+ * @throws {TypeError} If the URN is invalid.
+ * @example
+ * ```ts
+ * getOrganizationIdFromUrn('1') // throws TypeError
+ * getOrganizationIdFromUrn('urn:logto:organization:1') // returns '1'
+ * ```
+ */
+const getOrganizationIdFromUrn = (urn) => {
+    if (!urn.startsWith(organizationUrnPrefix)) {
+        throw new TypeError('Invalid organization URN.');
+    }
+    return urn.slice(organizationUrnPrefix.length);
+};
+
+export { ReservedResource, ReservedScope, UserScope, buildOrganizationUrn, getOrganizationIdFromUrn, idTokenClaims, organizationUrnPrefix, userClaims, userinfoClaims };

package/lib/core/fetch-token.cjs

@@ -24,7 +24,14 @@ const fetchTokenByAuthorizationCode = async ({ clientId, tokenEndpoint, redirect
     });
     return camelcaseKeys__default.default(snakeCaseCodeTokenResponse);
 };
-const fetchTokenByRefreshToken = async ({ clientId, tokenEndpoint, refreshToken, resource, scopes }, requester) => {
+/**
+ * Fetch access token by refresh token using the token endpoint and `refresh_token` grant type.
+ * @param params The parameters for fetching access token.
+ * @param requester The requester for sending HTTP request.
+ * @returns A Promise that resolves to the access token response.
+ */
+const fetchTokenByRefreshToken = async (params, requester) => {
+    const { clientId, tokenEndpoint, refreshToken, resource, organizationId, scopes } = params;
     const parameters = new URLSearchParams();
     parameters.append(index.QueryKey.ClientId, clientId);
     parameters.append(index.QueryKey.RefreshToken, refreshToken);
@@ -32,6 +39,9 @@ const fetchTokenByRefreshToken = async ({ clientId, tokenEndpoint, refreshToken,
     if (resource) {
         parameters.append(index.QueryKey.Resource, resource);
     }
+    if (organizationId) {
+        parameters.append(index.QueryKey.OrganizationId, organizationId);
+    }
     if (scopes?.length) {
         parameters.append(index.QueryKey.Scope, scopes.join(' '));
     }

package/lib/core/fetch-token.d.ts

@@ -9,10 +9,20 @@ export type FetchTokenByAuthorizationCodeParameters = {
     resource?: string;
 };
 export type FetchTokenByRefreshTokenParameters = {
+    /** The client ID of the application. */
     clientId: string;
+    /** The token endpoint of the authorization server. */
     tokenEndpoint: string;
+    /** The refresh token to be used to fetch the organization access token. */
     refreshToken: string;
+    /** The API resource to be fetch the access token for. */
     resource?: string;
+    /** The ID of the organization to be fetch the access token for. */
+    organizationId?: string;
+    /**
+     * The scopes to request for the access token. If not provided, the authorization server
+     * will use all the scopes that the client is authorized for.
+     */
     scopes?: string[];
 };
 type SnakeCaseCodeTokenResponse = {
@@ -25,12 +35,18 @@ type SnakeCaseCodeTokenResponse = {
 export type CodeTokenResponse = KeysToCamelCase<SnakeCaseCodeTokenResponse>;
 type SnakeCaseRefreshTokenTokenResponse = {
     access_token: string;
-    refresh_token: string;
+    refresh_token?: string;
     id_token?: string;
     scope: string;
     expires_in: number;
 };
 export type RefreshTokenTokenResponse = KeysToCamelCase<SnakeCaseRefreshTokenTokenResponse>;
 export declare const fetchTokenByAuthorizationCode: ({ clientId, tokenEndpoint, redirectUri, codeVerifier, code, resource, }: FetchTokenByAuthorizationCodeParameters, requester: Requester) => Promise<CodeTokenResponse>;
-export declare const fetchTokenByRefreshToken: ({ clientId, tokenEndpoint, refreshToken, resource, scopes }: FetchTokenByRefreshTokenParameters, requester: Requester) => Promise<RefreshTokenTokenResponse>;
+/**
+ * Fetch access token by refresh token using the token endpoint and `refresh_token` grant type.
+ * @param params The parameters for fetching access token.
+ * @param requester The requester for sending HTTP request.
+ * @returns A Promise that resolves to the access token response.
+ */
+export declare const fetchTokenByRefreshToken: (params: FetchTokenByRefreshTokenParameters, requester: Requester) => Promise<RefreshTokenTokenResponse>;
 export {};

package/lib/core/fetch-token.js

@@ -18,7 +18,14 @@ const fetchTokenByAuthorizationCode = async ({ clientId, tokenEndpoint, redirect
     });
     return camelcaseKeys(snakeCaseCodeTokenResponse);
 };
-const fetchTokenByRefreshToken = async ({ clientId, tokenEndpoint, refreshToken, resource, scopes }, requester) => {
+/**
+ * Fetch access token by refresh token using the token endpoint and `refresh_token` grant type.
+ * @param params The parameters for fetching access token.
+ * @param requester The requester for sending HTTP request.
+ * @returns A Promise that resolves to the access token response.
+ */
+const fetchTokenByRefreshToken = async (params, requester) => {
+    const { clientId, tokenEndpoint, refreshToken, resource, organizationId, scopes } = params;
     const parameters = new URLSearchParams();
     parameters.append(QueryKey.ClientId, clientId);
     parameters.append(QueryKey.RefreshToken, refreshToken);
@@ -26,6 +33,9 @@ const fetchTokenByRefreshToken = async ({ clientId, tokenEndpoint, refreshToken,
     if (resource) {
         parameters.append(QueryKey.Resource, resource);
     }
+    if (organizationId) {
+        parameters.append(QueryKey.OrganizationId, organizationId);
+    }
     if (scopes?.length) {
         parameters.append(QueryKey.Scope, scopes.join(' '));
     }

package/lib/index.cjs

@@ -13,6 +13,7 @@ var accessToken = require('./utils/access-token.cjs');
 var scopes = require('./utils/scopes.cjs');
 var arbitraryObject = require('./utils/arbitrary-object.cjs');
 var index = require('./consts/index.cjs');
+var openid = require('./consts/openid.cjs');
 
 
 
@@ -44,15 +45,25 @@ Object.defineProperty(exports, 'QueryKey', {
 	enumerable: true,
 	get: function () { return index.QueryKey; }
 });
-Object.defineProperty(exports, 'ReservedScope', {
-	enumerable: true,
-	get: function () { return index.ReservedScope; }
-});
 Object.defineProperty(exports, 'TokenGrantType', {
 	enumerable: true,
 	get: function () { return index.TokenGrantType; }
 });
+Object.defineProperty(exports, 'ReservedResource', {
+	enumerable: true,
+	get: function () { return openid.ReservedResource; }
+});
+Object.defineProperty(exports, 'ReservedScope', {
+	enumerable: true,
+	get: function () { return openid.ReservedScope; }
+});
 Object.defineProperty(exports, 'UserScope', {
 	enumerable: true,
-	get: function () { return index.UserScope; }
+	get: function () { return openid.UserScope; }
 });
+exports.buildOrganizationUrn = openid.buildOrganizationUrn;
+exports.getOrganizationIdFromUrn = openid.getOrganizationIdFromUrn;
+exports.idTokenClaims = openid.idTokenClaims;
+exports.organizationUrnPrefix = openid.organizationUrnPrefix;
+exports.userClaims = openid.userClaims;
+exports.userinfoClaims = openid.userinfoClaims;

package/lib/index.js

@@ -10,4 +10,5 @@ export { decodeIdToken, verifyIdToken } from './utils/id-token.js';
 export { decodeAccessToken } from './utils/access-token.js';
 export { withDefaultScopes } from './utils/scopes.js';
 export { isArbitraryObject } from './utils/arbitrary-object.js';
-export { ContentType, Prompt, QueryKey, ReservedScope, TokenGrantType, UserScope } from './consts/index.js';
+export { ContentType, Prompt, QueryKey, TokenGrantType } from './consts/index.js';
+export { ReservedResource, ReservedScope, UserScope, buildOrganizationUrn, getOrganizationIdFromUrn, idTokenClaims, organizationUrnPrefix, userClaims, userinfoClaims } from './consts/openid.js';

package/lib/utils/id-token.d.ts

@@ -1,19 +1,46 @@
 import type { Nullable } from '@silverhand/essentials';
 import type { JWTVerifyGetKey } from 'jose';
 export type IdTokenClaims = {
+    /** Issuer of this token. */
     iss: string;
+    /** Subject (the user ID) of this token. */
     sub: string;
+    /** Audience (the client ID) of this token. */
     aud: string;
+    /** Expiration time of this token. */
     exp: number;
+    /** Time at which this token was issued. */
     iat: number;
     at_hash?: Nullable<string>;
+    /** Full name of the user. */
     name?: Nullable<string>;
+    /** Username of the user. */
     username?: Nullable<string>;
+    /** URL of the user's profile picture. */
     picture?: Nullable<string>;
+    /** Email address of the user. */
     email?: Nullable<string>;
+    /** Whether the user's email address has been verified. */
     email_verified?: boolean;
+    /** Phone number of the user. */
     phone_number?: Nullable<string>;
+    /** Whether the user's phone number has been verified. */
     phone_number_verified?: boolean;
-};
+    /** Organization IDs that the user has membership in. */
+    organizations?: string[];
+    /**
+     * All organization roles that the user has. The format is `{organizationId}:{roleName}`.
+     *
+     * Note that not all organizations are included in this list, only the ones that the user has roles in.
+     *
+     * @example
+     * ```ts
+     * ['org1:admin', 'org2:member'] // The user is an admin of org1 and a member of org2.
+     * ```
+     */
+    organization_roles?: string[];
+    /** Roles that the user has for API resources. */
+    roles?: string[];
+} & Record<string, unknown>;
 export declare const verifyIdToken: (idToken: string, clientId: string, issuer: string, jwks: JWTVerifyGetKey) => Promise<void>;
 export declare const decodeIdToken: (token: string) => IdTokenClaims;

package/lib/utils/scopes.cjs

@@ -1,14 +1,15 @@
 'use strict';
 
-var index = require('../consts/index.cjs');
+require('../consts/index.cjs');
+var openid = require('../consts/openid.cjs');
 
 /**
  * @param originalScopes
  * @return scopes should contain all default scopes (`openid`, `offline_access` and `profile`)
  */
 const withDefaultScopes = (originalScopes) => {
-    const reservedScopes = Object.values(index.ReservedScope);
-    const uniqueScopes = new Set([...reservedScopes, index.UserScope.Profile, ...(originalScopes ?? [])]);
+    const reservedScopes = Object.values(openid.ReservedScope);
+    const uniqueScopes = new Set([...reservedScopes, openid.UserScope.Profile, ...(originalScopes ?? [])]);
     return Array.from(uniqueScopes).join(' ');
 };
 

package/lib/utils/scopes.js

@@ -1,4 +1,5 @@
-import { ReservedScope, UserScope } from '../consts/index.js';
+import '../consts/index.js';
+import { ReservedScope, UserScope } from '../consts/openid.js';
 
 /**
  * @param originalScopes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/js",
-  "version": "2.1.2",
+  "version": "3.0.0",
   "type": "module",
   "main": "./lib/index.cjs",
   "module": "./lib/index.js",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@silverhand/essentials": "^2.6.2",
     "camelcase-keys": "^7.0.1",
-    "jose": "^4.13.2"
+    "jose": "^5.0.0"
   },
   "devDependencies": {
     "@silverhand/eslint-config": "^4.0.1",
@@ -35,12 +35,12 @@
     "jest": "^29.5.0",
     "jest-environment-jsdom": "^29.5.0",
     "jest-matcher-specific-error": "^1.0.0",
-    "lint-staged": "^13.0.0",
+    "lint-staged": "^15.0.0",
     "nock": "^13.3.0",
     "prettier": "^3.0.0",
     "rollup": "^3.20.2",
     "text-encoder": "^0.0.4",
-    "type-fest": "^3.0.0",
+    "type-fest": "^4.0.0",
     "typescript": "^5.0.0"
   },
   "eslintConfig": {