@meistrari/auth-core 1.14.0 → 1.16.0

package/dist/index.mjs

@@ -8,7 +8,7 @@ import { defaultStatements } from 'better-auth/plugins/organization/access';
 import { z } from 'zod';
 export { APIError } from 'better-auth';
 
-const version = "1.14.0";
+const version = "1.16.0";
 
 const statements = {
   ...defaultStatements,
@@ -171,12 +171,17 @@ function applicationsPluginClient() {
               headers
             });
           },
-          whoAmI: async (accessToken) => {
+          whoAmI: async (accessToken, options = {}) => {
             const headers = new Headers();
             headers.set("x-tela-access-token", accessToken);
+            const query = {};
+            if (options.include && options.include.length > 0) {
+              query.include = options.include.join(",");
+            }
             return await $fetch("/applications/whoami", {
               method: "GET",
-              headers
+              headers,
+              query
             });
           },
           switchOrganization: async (organizationId, accessToken) => {
@@ -255,7 +260,13 @@ function createAPIClient(apiUrl, fetchOptions = {}) {
 }
 
 class BaseError extends Error {
+  /** Machine-readable error code (e.g. `"INVALID_SOCIAL_PROVIDER"`). */
   code;
+  /**
+   * @param code - A machine-readable error code
+   * @param message - A human-readable error message
+   * @param options - Standard `ErrorOptions` (e.g. `cause`)
+   */
   constructor(code, message, options) {
     super(message, options);
     this.code = code;
@@ -389,6 +400,16 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Starts a device authorization flow (RFC 8628).
+   *
+   * Returns a device code and user code that the end user must enter
+   * on the verification URI to authorize the device.
+   *
+   * @param requesterApplicationId - The application requesting authorization
+   * @param targetApplicationId - The target application to gain access to
+   * @returns Device authorization details including codes and verification URI
+   */
   async startDeviceAuthorizationFlow(requesterApplicationId, targetApplicationId) {
     const response = await this.client.applications.startDeviceAuthorizationFlow(requesterApplicationId, targetApplicationId);
     if (!response.data) {
@@ -396,6 +417,15 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Retrieves the context for a pending device authorization request.
+   *
+   * Used by the authorization page to display details about the requesting
+   * and target applications before the user approves or denies.
+   *
+   * @param userCode - The user code from the device authorization response
+   * @returns Context including application info, available organizations, and status
+   */
   async getDeviceAuthorizationContext(userCode) {
     const response = await this.client.applications.getDeviceAuthorizationContext(userCode);
     if (!response.data) {
@@ -403,6 +433,13 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Approves a pending device authorization request.
+   *
+   * @param userCode - The user code identifying the device authorization request
+   * @param organizationId - The organization to authorize the device for
+   * @returns Confirmation of the approval action
+   */
   async approveDeviceAuthorizationFlow(userCode, organizationId) {
     const response = await this.client.applications.approveDeviceAuthorizationFlow(userCode, organizationId);
     if (!response.data) {
@@ -410,6 +447,12 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Denies a pending device authorization request.
+   *
+   * @param userCode - The user code identifying the device authorization request
+   * @returns Confirmation of the denial action
+   */
   async denyDeviceAuthorizationFlow(userCode) {
     const response = await this.client.applications.denyDeviceAuthorizationFlow(userCode);
     if (!response.data) {
@@ -417,12 +460,33 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Exchanges a device code for access and refresh tokens.
+   *
+   * This should be called by the device client while polling. It will throw
+   * typed errors to indicate the polling state (pending, slow down, denied, expired).
+   *
+   * @param deviceCode - The device code obtained from {@link startDeviceAuthorizationFlow}
+   * @returns Access and refresh tokens along with user and organization info
+   *
+   * @throws {DeviceAuthorizationPendingError} The user hasn't authorized yet — keep polling
+   * @throws {DeviceAuthorizationSlowDownError} Polling too fast — increase the interval
+   * @throws {DeviceAccessDeniedError} The user denied the request
+   * @throws {DeviceCodeExpiredError} The device code has expired
+   * @throws {DeviceTransientServerError} Transient server error — safe to retry
+   */
   async exchangeDeviceCodeForTokens(deviceCode) {
-    const response = await this.client.applications.exchangeDeviceCodeForTokens(deviceCode);
-    if (!response.data) {
-      throwDeviceGrantError(response.error);
+    try {
+      const response = await this.client.applications.exchangeDeviceCodeForTokens(deviceCode);
+      if (!response.data) {
+        throwDeviceGrantError(response.error);
+      }
+      return response.data;
+    } catch (error) {
+      if (error instanceof ApplicationError)
+        throw error;
+      throwDeviceGrantError(error);
     }
-    return response.data;
   }
   /**
    * Completes an authorization flow for a specific application.
@@ -445,25 +509,39 @@ class ApplicationService {
    * @throws {ApplicationError} For other API errors
    */
   async refreshAccessToken(refreshToken) {
-    const response = await this.client.applications.refreshAccessToken(refreshToken);
-    if (!response.data) {
-      const error = response.error;
+    const handleRefreshError = (error) => {
       const status = error?.status;
       if (status === 404) {
         throw new RefreshTokenExpiredError({ cause: error });
       }
-      throw new ApplicationError(error?.message || "Failed to refresh access token", { cause: error });
+      const message = error?.message;
+      throw new ApplicationError(message || "Failed to refresh access token", { cause: error });
+    };
+    try {
+      const response = await this.client.applications.refreshAccessToken(refreshToken);
+      if (!response.data) {
+        handleRefreshError(response.error);
+      }
+      return response.data;
+    } catch (error) {
+      if (error instanceof ApplicationError)
+        throw error;
+      handleRefreshError(error);
     }
-    return response.data;
   }
   /**
    * Gets the current user and organization for a specific application.
    *
+   * By default, the returned organization does not include its `members`,
+   * `teams`, or `invitations` collections. Pass `options.include` to request
+   * any of them explicitly.
+   *
    * @param accessToken - The access token to use for the who am I request
+   * @param options - Optional include list controlling which relations are loaded
    * @returns The current user and organization
    */
-  async whoAmI(accessToken) {
-    const response = await this.client.applications.whoAmI(accessToken);
+  async whoAmI(accessToken, options = {}) {
+    const response = await this.client.applications.whoAmI(accessToken, options);
     if (!response.data) {
       throw new Error("No data returned from the API", { cause: response.error });
     }
@@ -545,10 +623,7 @@ class OrganizationService {
   /**
    * Updates an organization's details.
    *
-   * @param payload - The organization fields to update
-   * @param payload.name - New organization name
-   * @param payload.logo - New organization logo URL
-   * @param payload.settings - New organization settings
+   * @param payload - The organization fields to update (name, logo, settings)
    * @returns The updated organization
    */
   async updateOrganization(payload) {
@@ -623,9 +698,7 @@ class OrganizationService {
   /**
    * Removes a user from the active organization.
    *
-   * @param options - User identifier (either memberId or userEmail must be provided)
-   * @param options.memberId - The member ID to remove
-   * @param options.userEmail - The user email to remove
+   * @param options - Provide either `memberId` or `userEmail` to identify the user
    */
   async removeUserFromOrganization({ memberId, userEmail }) {
     await this.client.organization.removeMember({
@@ -648,8 +721,7 @@ class OrganizationService {
   /**
    * Creates a new team within the active organization.
    *
-   * @param payload - Team configuration
-   * @param payload.name - The name of the team
+   * @param payload - Team configuration with a `name` field
    * @returns The created team
    */
   async createTeam(payload) {
@@ -659,8 +731,7 @@ class OrganizationService {
    * Updates an existing team's details.
    *
    * @param id - The team ID to update
-   * @param payload - Team fields to update
-   * @param payload.name - The new team name
+   * @param payload - Team fields to update (currently supports `name`)
    * @returns The updated team
    */
   async updateTeam(id, payload) {
@@ -919,6 +990,15 @@ class ApiKeyService {
   constructor(client) {
     this.client = client;
   }
+  /**
+   * Creates a new API key.
+   *
+   * The returned object includes the secret `key` value, which is only
+   * available at creation time and cannot be retrieved later.
+   *
+   * @param payload - The API key configuration
+   * @returns The created API key including the secret key value
+   */
   async createApiKey(payload) {
     return await this.client.apiKey.create({
       name: payload.name,
@@ -927,6 +1007,12 @@ class ApiKeyService {
       metadata: payload.metadata
     });
   }
+  /**
+   * Retrieves an API key by its ID.
+   *
+   * @param id - The API key ID
+   * @returns The API key (without the secret key value)
+   */
   async getApiKey(id) {
     return await this.client.apiKey.get({
       query: {
@@ -934,18 +1020,39 @@ class ApiKeyService {
       }
     });
   }
+  /**
+   * Lists all API keys owned by the authenticated user.
+   *
+   * @returns An object containing the API keys array and pagination metadata
+   */
   async listApiKeys() {
     return await this.client.apiKey.list();
   }
+  /**
+   * Lists all API keys belonging to the active organization.
+   *
+   * @returns An array of API keys (without secret key values)
+   */
   async listOrganizationApiKeys() {
     return await this.client.customEndpoints.organizations.apiKeys();
   }
+  /**
+   * Updates an existing API key.
+   *
+   * @param payload - The fields to update
+   * @returns The updated API key (without the secret key value)
+   */
   async updateApiKey(payload) {
     return await this.client.apiKey.update({
       keyId: payload.id,
       name: payload.name
     });
   }
+  /**
+   * Permanently deletes an API key.
+   *
+   * @param id - The API key ID to delete
+   */
   async deleteApiKey(id) {
     return await this.client.apiKey.delete({
       keyId: id

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-core",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "type": "module",
   "exports": {
     ".": {
@@ -14,7 +14,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "unbuild"
+    "build": "unbuild",
+    "docs": "typedoc"
   },
   "dependencies": {
     "@better-auth/api-key": "1.5.4",
@@ -25,6 +26,8 @@
   },
   "devDependencies": {
     "@types/node": "latest",
+    "typedoc": "0.28.18",
+    "typedoc-plugin-markdown": "4.11.0",
     "typescript": "5.9.2",
     "unbuild": "3.6.1"
   }