@netlify/identity 0.4.2 → 1.0.0

package/README.md

@@ -3,23 +3,24 @@
 A lightweight, no-config headless authentication library for projects using Netlify Identity. Works in both browser and server contexts.
 This is NOT the Netlify Identity Widget. This library exports standalone async functions (e.g., import { login, getUser } from '@netlify/identity'). There is no class to instantiate and no .init() call. Just import the functions you need and call them.
 
-> **Status:** Beta. The API may change before 1.0.
-
 **Prerequisites:**
 
-- [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project
+- [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project. This happens automatically when running within a [Netlify Agent Runner](https://docs.netlify.com/agent-runner/overview/)
 - **Server-side** functions (`getUser`, `login`, `admin.*`, etc.) require [Netlify Functions](https://docs.netlify.com/build/functions/get-started/) (modern/v2, with `export default`) or [Edge Functions](https://docs.netlify.com/edge-functions/overview/). [Lambda-compatible functions](https://docs.netlify.com/build/functions/lambda-compatibility/) (v1, with `export { handler }`) are **not supported**
 - For local development, use [`netlify dev`](https://docs.netlify.com/cli/local-development/) so the Identity endpoint is available
 
 ## How this library relates to other Netlify auth packages
 
-| Package                                                                         | What it is                                     | When to use it                                                                             |
-| ------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| **`@netlify/identity`** (this library)                                          | Headless TypeScript API for browser and server | You want full control over your auth UI and need server-side auth (SSR, Netlify Functions) |
-| [`netlify-identity-widget`](https://github.com/netlify/netlify-identity-widget) | Pre-built login/signup modal (HTML + CSS)      | You want a drop-in UI component with no custom design                                      |
-| [`gotrue-js`](https://github.com/netlify/gotrue-js)                             | Low-level GoTrue HTTP client (browser only)    | You're building your own auth wrapper and need direct API access                           |
+`@netlify/identity` is the recommended library for all new projects. It works in both browser and server contexts, handles cookie management, and normalizes the user object.
+
+You may encounter two older packages in existing code or documentation:
 
-This library provides a unified API that works in both browser and server contexts, handles cookie management, and normalizes the user object. You do not need to install `gotrue-js` or the widget separately.
+| Package                                                                         | Status                           | What it was                                   |
+| ------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------- |
+| [`netlify-identity-widget`](https://github.com/netlify/netlify-identity-widget) | Not recommended for new projects | Pre-built login/signup modal with built-in UI |
+| [`gotrue-js`](https://github.com/netlify/gotrue-js)                             | Not recommended for new projects | Low-level GoTrue HTTP client (browser only)   |
+
+If you need a pre-built login UI, the widget still works. For everything else (custom UI, server-side auth, admin operations, framework integration), use `@netlify/identity`.
 
 ## Table of contents
 
@@ -97,7 +98,7 @@ export default async (req: Request, context: Context) => {
 getUser(): Promise<User | null>
 ```
 
-Returns the current authenticated user, or `null` if not logged in. Returns the best available normalized `User` from the current context. In the browser or when the server can reach the Identity API, all fields are populated. When falling back to JWT claims (e.g., Identity API unreachable), fields like `createdAt`, `updatedAt`, `emailVerified`, and `rawGoTrueData` may be missing. Never throws.
+Returns the current authenticated user, or `null` if not logged in. Returns the best available normalized `User` from the current context. When the Identity API is reachable, most persisted and profile fields are populated, but state-dependent fields (invite, recovery, email-change) may still be `undefined` if the user is not in that state. When falling back to JWT claims (e.g., Identity API unreachable), only `id`, `email`, `provider`, `name`, `pictureUrl`, `roles`, `userMetadata`, and `appMetadata` are available. Never throws.
 
 > **Next.js note:** Calling `getUser()` in a Server Component opts the page into [dynamic rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering) because it reads cookies. This is expected and correct for authenticated pages. Next.js handles the internal dynamic rendering signal automatically.
 
@@ -173,7 +174,7 @@ oauthLogin(provider: string): never
 
 Redirects to an OAuth provider. The page navigates away, so this function never returns normally. Browser only.
 
-The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`, `'facebook'`, or `'saml'`.
+The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`, or `'facebook'`.
 
 **Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if called on the server.
 
@@ -361,7 +362,7 @@ Gets a single user by ID.
 admin.createUser(params: CreateUserParams): Promise<User>
 ```
 
-Creates a new user. The user is auto-confirmed. Optional `data` forwards allowed fields (`role`, `aud`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored. `data` cannot override `email`, `password`, or `confirm`.
+Creates a new user. The user is auto-confirmed. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored. `data` cannot override `email`, `password`, or `confirm`.
 
 **Throws:** `AuthError` if called from a browser, the email already exists, or the operator token is missing.
 
@@ -393,16 +394,22 @@ Deletes a user by ID.
 interface User {
   id: string
   email?: string
-  emailVerified?: boolean
+  confirmedAt?: string
   createdAt?: string
   updatedAt?: string
+  role?: string
   provider?: AuthProvider
   name?: string
   pictureUrl?: string
   roles?: string[]
-  metadata?: Record<string, unknown>
+  invitedAt?: string
+  confirmationSentAt?: string
+  recoverySentAt?: string
+  pendingEmail?: string
+  emailChangeSentAt?: string
+  lastSignInAt?: string
+  userMetadata?: Record<string, unknown>
   appMetadata?: Record<string, unknown>
-  rawGoTrueData?: Record<string, unknown>
 }
 ```
 
@@ -428,7 +435,7 @@ interface IdentityConfig {
 #### `AuthProvider`
 
 ```ts
-type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'saml' | 'email'
+type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'email'
 ```
 
 #### `UserUpdates`
@@ -451,14 +458,13 @@ interface AdminUserUpdates {
   email?: string
   password?: string
   role?: string
-  aud?: string
   confirm?: boolean
   app_metadata?: Record<string, unknown>
   user_metadata?: Record<string, unknown>
 }
 ```
 
-Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, `aud`, force-confirm a user, and write to `app_metadata`. Only these typed fields are forwarded.
+Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, force-confirm a user, and write to `app_metadata`. Only these typed fields are forwarded.
 
 #### `SignupData`
 
@@ -499,7 +505,7 @@ interface CreateUserParams {
 }
 ```
 
-Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `aud`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored.
+Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored.
 
 #### `Admin`
 

package/dist/index.cjs

@@ -56,7 +56,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
-var AUTH_PROVIDERS = ["google", "github", "gitlab", "bitbucket", "facebook", "saml", "email"];
+var AUTH_PROVIDERS = ["google", "github", "gitlab", "bitbucket", "facebook", "email"];
 
 // src/environment.ts
 var import_gotrue_js = __toESM(require("gotrue-js"), 1);
@@ -681,6 +681,7 @@ var hydrateSession = async () => {
 
 // src/user.ts
 var toAuthProvider = (value) => typeof value === "string" && AUTH_PROVIDERS.includes(value) ? value : void 0;
+var toOptionalString = (value) => typeof value === "string" && value !== "" ? value : void 0;
 var toRoles = (appMeta) => {
   const roles = appMeta.roles;
   if (Array.isArray(roles) && roles.every((r) => typeof r === "string")) {
@@ -693,20 +694,25 @@ var toUser = (userData) => {
   const appMeta = userData.app_metadata ?? {};
   const name = userMeta.full_name || userMeta.name;
   const pictureUrl = userMeta.avatar_url;
-  const { token: _token, ...safeUserData } = userData;
   return {
     id: userData.id,
     email: userData.email,
-    emailVerified: !!userData.confirmed_at,
+    confirmedAt: toOptionalString(userData.confirmed_at),
     createdAt: userData.created_at,
     updatedAt: userData.updated_at,
+    role: toOptionalString(userData.role),
     provider: toAuthProvider(appMeta.provider),
     name: typeof name === "string" ? name : void 0,
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
-    metadata: userMeta,
-    appMetadata: appMeta,
-    rawGoTrueData: { ...safeUserData }
+    invitedAt: toOptionalString(userData.invited_at),
+    confirmationSentAt: toOptionalString(userData.confirmation_sent_at),
+    recoverySentAt: toOptionalString(userData.recovery_sent_at),
+    pendingEmail: toOptionalString(userData.new_email),
+    emailChangeSentAt: toOptionalString(userData.email_change_sent_at),
+    lastSignInAt: toOptionalString(userData.last_sign_in_at),
+    userMetadata: userMeta,
+    appMetadata: appMeta
   };
 };
 var claimsToUser = (claims) => {
@@ -721,7 +727,7 @@ var claimsToUser = (claims) => {
     name: typeof name === "string" ? name : void 0,
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
-    metadata: userMeta,
+    userMetadata: userMeta,
     appMetadata: appMeta
   };
 };
@@ -818,8 +824,7 @@ var getSettings = async () => {
         gitlab: external.gitlab ?? false,
         bitbucket: external.bitbucket ?? false,
         facebook: external.facebook ?? false,
-        email: external.email ?? false,
-        saml: external.saml ?? false
+        email: external.email ?? false
       }
     };
   } catch (err) {
@@ -996,7 +1001,7 @@ var createUser = async (params) => {
     confirm: true
   };
   if (params.data) {
-    const allowedKeys = ["role", "aud", "app_metadata", "user_metadata"];
+    const allowedKeys = ["role", "app_metadata", "user_metadata"];
     for (const key of allowedKeys) {
       if (key in params.data) {
         body[key] = params.data[key];
@@ -1014,7 +1019,7 @@ var updateUser2 = async (userId, attributes) => {
   assertServer();
   const sanitizedUserId = sanitizeUserId(userId);
   const body = {};
-  const allowedKeys = ["email", "password", "role", "aud", "confirm", "app_metadata", "user_metadata"];
+  const allowedKeys = ["email", "password", "role", "confirm", "app_metadata", "user_metadata"];
   for (const key of allowedKeys) {
     if (key in attributes) {
       body[key] = attributes[key];