@meistrari/auth-core 1.15.0 → 1.17.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.15.0";
+const version = "1.17.0";
 
 const statements = {
   ...defaultStatements,
@@ -61,6 +61,13 @@ const memberAdditionalFields = {
     defaultValue: null
   }
 };
+const invitationAdditionalFields = {
+  applicationId: {
+    type: "string",
+    input: true,
+    required: false
+  }
+};
 const JWTPayloadUser = z.object({
   id: z.string(),
   name: z.string(),
@@ -100,6 +107,12 @@ function applicationsPluginClient() {
               }
             };
           },
+          inviteUserToApplication: async (options) => {
+            return await $fetch("/applications/invitations", {
+              method: "POST",
+              body: options
+            });
+          },
           startAuthorizationFlow: async (applicationId, redirectUri, codeChallenge, organizationId) => {
             return await $fetch("/applications/authorize", {
               method: "POST",
@@ -171,12 +184,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 +273,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;
@@ -374,6 +398,20 @@ class ApplicationService {
     }
     return response.data;
   }
+  /**
+   * Invites a user to an application through an organization entitlement.
+   *
+   * @param options - Invitation details including organization, application, email, and role
+   * @returns The created invitation
+   */
+  async inviteUserToApplication(options) {
+    const response = await this.client.applications.inviteUserToApplication(options);
+    const invitation = response.data;
+    if (!invitation) {
+      throw new Error("No invitation returned from application invitation endpoint");
+    }
+    return invitation;
+  }
   /**
    * Starts an authorization flow for a specific application.
    *
@@ -389,6 +427,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 +444,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 +460,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 +474,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,6 +487,21 @@ 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) {
     try {
       const response = await this.client.applications.exchangeDeviceCodeForTokens(deviceCode);
@@ -474,11 +559,16 @@ class ApplicationService {
   /**
    * 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 });
     }
@@ -560,10 +650,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) {
@@ -604,16 +691,19 @@ class OrganizationService {
    * @param options.userEmail - Email address of the user to invite
    * @param options.role - Role to assign to the invited user
    * @param options.teamId - Team ID to add the user to
+   * @param options.applicationId - Legacy application scope; prefer applications.inviteUserToApplication for new app-scoped invites
    * @param options.resend - Whether to resend if invitation already exists
    * @returns The created invitation
    */
-  async inviteUserToOrganization({ userEmail, role, teamId, resend }) {
-    return await this.client.organization.inviteMember({
+  async inviteUserToOrganization({ userEmail, role, teamId, resend, applicationId }) {
+    const invitation = {
       email: userEmail,
       role,
       teamId,
-      resend: resend ?? false
-    });
+      resend: resend ?? false,
+      applicationId
+    };
+    return await this.client.organization.inviteMember(invitation);
   }
   /**
    * Cancels a pending organization invitation.
@@ -629,18 +719,19 @@ class OrganizationService {
    * Accepts an organization invitation.
    *
    * @param id - The invitation ID to accept
+   * @returns Object containing the application's `homeUrl` when the invitation is
+   *   scoped to an application that defines one; otherwise `null`.
    */
   async acceptInvitation(id) {
-    await this.client.organization.acceptInvitation({
+    const response = await this.client.organization.acceptInvitation({
       invitationId: id
     });
+    return { homeUrl: response?.homeUrl ?? null };
   }
   /**
    * 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({
@@ -663,8 +754,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) {
@@ -674,8 +764,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) {
@@ -934,6 +1023,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,
@@ -942,6 +1040,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: {
@@ -949,18 +1053,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
@@ -1034,4 +1159,4 @@ function extractTokenPayload(token) {
   return payload;
 }
 
-export { ApplicationError, AuthClient, AuthorizationFlowError, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadUser, JWTPayloadWorkspace, RefreshTokenExpiredError, Roles, UserNotLoggedInError, ac, extractTokenPayload, isTokenExpired, memberAdditionalFields, organizationAdditionalFields, rolesAccessControl, userAdditionalFields, validateToken };
+export { ApplicationError, AuthClient, AuthorizationFlowError, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadUser, JWTPayloadWorkspace, RefreshTokenExpiredError, Roles, UserNotLoggedInError, ac, extractTokenPayload, invitationAdditionalFields, isTokenExpired, memberAdditionalFields, organizationAdditionalFields, rolesAccessControl, userAdditionalFields, validateToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-core",
-  "version": "1.15.0",
+  "version": "1.17.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"
   }