@faable/auth-js 1.7.0 → 1.7.2

package/README.md

@@ -18,6 +18,10 @@
   </a>
 </p>
 
+<p align="center">
+  📚 Full documentation at <a href="https://faable.com/docs">faable.com/docs</a>
+</p>
+
 ## Features
 
 - OAuth social connections (Google, GitHub, …) with PKCE and implicit flows
@@ -249,6 +253,11 @@ Pass the same `clientId` you used in `createClient`. If you also passed a custom
 `storageKey` to `createClient`, mirror it here as `{ clientId, storageKey }` so
 the helper looks at the same cookie.
 
+## Documentation
+
+For the full guides, API reference, and dashboard setup walkthroughs visit
+[faable.com/docs](https://faable.com/docs).
+
 ## License
 
 See [LICENSE.md](LICENSE.md).

package/dist/dts/FaableAuthClient.d.ts

@@ -15,6 +15,7 @@ export declare class FaableAuthClient extends Base {
     tokenIssuer: string;
     redirectUri: string;
     scope?: string;
+    audience?: string;
     sessionCheckExpiryDays: number;
     protected initializePromise: Promise<InitializeResult> | null;
     protected detectSessionInUrl: boolean;
@@ -38,15 +39,57 @@ export declare class FaableAuthClient extends Base {
      */
     protected flowType: AuthFlowType;
     protected lock: Lock;
+    /**
+     * Creates a new authentication client bound to a Faable Auth tenant.
+     *
+     * The constructor kicks off {@link FaableAuthClient.initialize} in the
+     * background; you do not need to await anything before calling other methods.
+     * Prefer the {@link createClient} factory in app code — it has the same
+     * effect with less ceremony.
+     *
+     * @param config Tenant settings. `domain` and `clientId` are required and
+     *   throw synchronously when missing.
+     * @example
+     * ```ts
+     * const auth = new FaableAuthClient({
+     *   domain: '<faableauth_domain>',
+     *   clientId: '<client_id>',
+     *   redirectUri: window.location.origin
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/get-started | Get Started with Faable Auth}
+     * @see {@link https://faable.com/docs/auth/clients | Clients}
+     */
     constructor(config: FaableAuthClientConfig);
     /**
-     * Returns the current session, if any.
+     * Cached session value last persisted by the client.
+     *
+     * This is a synchronous accessor that returns whatever the client has
+     * already loaded into memory. It can lag behind storage (for example,
+     * across tabs before the broadcast event arrives) and never triggers a
+     * refresh. Prefer {@link FaableAuthClient.getSession} when you need an
+     * authoritative value, especially on the server.
+     *
+     * @returns The cached {@link Session} or `null` if no user is signed in.
+     * @see {@link https://faable.com/docs/auth/oidc/userinfo | UserInfo}
      */
     get session(): Session | null;
     /**
-     * Initializes the client session either from the url or from storage.
-     * This method is automatically called when instantiating the client, but should also be called
-     * manually when checking for an error from an auth redirect (oauth, magiclink, password recovery, etc).
+     * Initializes the client session either from the URL or from storage.
+     *
+     * Automatically called once from the constructor and idempotent — extra
+     * calls return the same in-flight promise. Call it explicitly when you
+     * need to await an OAuth, magic link, or password-recovery redirect to
+     * finish processing so you can surface any returned error.
+     *
+     * @returns A promise that resolves to `{ error }` — non-null when the URL
+     *   carried a failure or storage was corrupt; never throws.
+     * @example
+     * ```ts
+     * const { error } = await auth.initialize()
+     * if (error) console.error('Auth redirect failed', error)
+     * ```
+     * @see {@link https://faable.com/docs/auth/oauth-flows/authorization-code | Authorization Code with PKCE}
      */
     initialize(): Promise<InitializeResult>;
     /**
@@ -79,8 +122,8 @@ export declare class FaableAuthClient extends Base {
     /**
      * Removes any registered visibilitychange callback.
      *
-     * {@see #startAutoRefresh}
-     * {@see #stopAutoRefresh}
+     * @see startAutoRefresh
+     * @see stopAutoRefresh
      */
     private _removeVisibilityChangedCallback;
     /**
@@ -103,7 +146,14 @@ export declare class FaableAuthClient extends Base {
      * platform's foreground indication mechanism and call these methods
      * appropriately to conserve resources.
      *
-     * {@see #stopAutoRefresh}
+     * @example
+     * ```ts
+     * // React Native / Node: drive the refresh loop on focus events yourself
+     * appState.addEventListener('change', state => {
+     *   if (state === 'active') auth.startAutoRefresh()
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/oauth-flows/refresh-token | Refresh Token}
      */
     startAutoRefresh(): Promise<void>;
     /**
@@ -123,41 +173,152 @@ export declare class FaableAuthClient extends Base {
     private _detectFlowType;
     private _scope;
     private _getUrlForConnection;
+    /**
+     * Starts an OAuth / social login by redirecting the browser to the tenant's
+     * `/authorize` endpoint for the chosen connection.
+     *
+     * In browsers the SDK redirects the current window unless
+     * `skipBrowserRedirect` is `true`; the call resolves to the authorization
+     * URL so you can drive the navigation yourself. PKCE is used by default in
+     * browsers, falling back to the implicit flow elsewhere. Prefer
+     * `connection_id` when known — the backend resolves it without an extra
+     * lookup; `connection` (by name) is kept for legacy tenants.
+     *
+     * @example
+     * ```ts
+     * await auth.signInWithOauthConnection({
+     *   connection: 'google',
+     *   redirectTo: 'https://app.example.com/callback'
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/connections | Connections}
+     * @see {@link https://faable.com/docs/auth/oauth-flows/authorization-code | Authorization Code with PKCE}
+     */
     signInWithOauthConnection(credentials: SignInWithOAuthConnection): Promise<OAuthResponse>;
+    /**
+     * Signs the user in with a username + password against a database
+     * connection on the tenant.
+     *
+     * The server responds with an HTML form that posts the user back to the
+     * tenant's `/login/callback` to complete the OAuth flow; the SDK
+     * auto-submits it from the current document. That is why the success path
+     * resolves to `{ data: null, error: null }` — the actual session lands on
+     * the redirect target, not on this return value. Subscribe with
+     * {@link FaableAuthClient.onAuthStateChange} to observe the resulting
+     * `SIGNED_IN` event.
+     *
+     * @example
+     * ```ts
+     * await auth.signInWithUsernamePassword({
+     *   username: 'user@example.com',
+     *   password: '••••••••',
+     *   redirectTo: 'https://app.example.com/callback'
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/connections | Connections}
+     */
     signInWithUsernamePassword(data: {
         username: string;
         password: string;
         redirectTo?: string;
         state?: string;
+        audience?: string;
     }): Promise<{
         data: null;
         error: AuthError | null;
     }>;
     /**
-     * Completes a passwordless login using an OTP code.
-     * @param data The username and OTP code.
+     * Completes a passwordless login by exchanging an OTP code for a session.
+     *
+     * Pair this with {@link FaableAuthClient.signInWithPasswordless} called
+     * with `type: 'code'`. On success the new session is persisted to storage
+     * and a `SIGNED_IN` event is broadcast.
+     *
+     * @param data The user identifier and the OTP code they received.
+     * @example
+     * ```ts
+     * const { data, error } = await auth.signInWithOtp({
+     *   username: 'user@example.com',
+     *   otp: '123456'
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/passwordless | Passwordless Authentication}
      */
     signInWithOtp(data: {
         username: string;
         otp: string;
+        audience?: string;
     }): Promise<AuthResponse>;
     /**
-     * Starts a passwordless login flow by requesting an OTP code or a magic link.
-     * @param data The email and the type of delivery (code or link).
+     * Starts a passwordless login flow by emailing the user either an OTP code
+     * or a magic link.
+     *
+     * - `type: 'code'` sends a short code the user pastes into your UI; finish
+     *   the flow with {@link FaableAuthClient.signInWithOtp}.
+     * - `type: 'link'` sends a clickable link that lands on your `redirectUri`
+     *   with the tokens already attached, processed by
+     *   {@link FaableAuthClient.initialize} on page load.
+     *
+     * @param data The user's email and the delivery mechanism.
+     * @example
+     * ```ts
+     * await auth.signInWithPasswordless({
+     *   email: 'user@example.com',
+     *   type: 'code'
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/passwordless | Passwordless Authentication}
      */
     signInWithPasswordless(data: {
         email: string;
         type: 'code' | 'link';
+        audience?: string;
     }): Promise<{
         data: any;
         error: AuthError | null;
     }>;
+    /**
+     * Triggers a "change your password" email for a database-connection user.
+     *
+     * The current session is unaffected — the user clicks the link in the
+     * email and completes the reset on the tenant's hosted pages. The promise
+     * resolves once the email has been queued.
+     *
+     * @param params The user's email address.
+     * @example
+     * ```ts
+     * await auth.changePassword({ email: 'user@example.com' })
+     * ```
+     * @see {@link https://faable.com/docs/auth/connections | Connections}
+     */
     changePassword(params: {
         email: string;
     }): Promise<{
         data: unknown;
         error: AuthError | null;
     }>;
+    /**
+     * Builds the tenant's `/authorize` URL without redirecting the browser.
+     *
+     * Useful when you need to render a login link, open the page in a popup,
+     * or hand the URL to a different runtime (e.g. a webview). For the
+     * everyday "click → redirect" flow use {@link FaableAuthClient.authorize}
+     * or {@link FaableAuthClient.signInWithOauthConnection}.
+     *
+     * The redirect target is resolved with this precedence:
+     * `options.redirectTo` → `config.redirectUri` → `window.location.origin`.
+     *
+     * @returns The fully-qualified authorize URL.
+     * @example
+     * ```ts
+     * const url = auth.buildAuthorizeUrl({
+     *   connection: 'google',
+     *   redirectTo: 'https://app.example.com/callback'
+     * })
+     * window.open(url, 'login', 'popup')
+     * ```
+     * @see {@link https://faable.com/docs/auth/oauth-flows/authorization-code | Authorization Code with PKCE}
+     */
     buildAuthorizeUrl(options?: {
         connection?: string;
         redirectTo?: string;
@@ -165,6 +326,22 @@ export declare class FaableAuthClient extends Base {
         response_type?: string;
         audience?: string;
     }): string;
+    /**
+     * Redirects the current window to the tenant's `/authorize` endpoint.
+     *
+     * Fire-and-forget: there is no return value because the browser navigates
+     * away. The session lands back on your `redirectUri`, where
+     * {@link FaableAuthClient.initialize} consumes it on the next page load.
+     *
+     * @example
+     * ```ts
+     * auth.authorize({
+     *   response_type: 'code',
+     *   redirectTo: 'https://app.example.com/callback'
+     * })
+     * ```
+     * @see {@link https://faable.com/docs/auth/oauth-flows/authorization-code | Authorization Code with PKCE}
+     */
     authorize(options: {
         redirectTo?: string;
         scope?: string;
@@ -173,9 +350,21 @@ export declare class FaableAuthClient extends Base {
     }): void;
     private _handleConnectionSignIn;
     /**
-     * Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session.
-     * If the refresh token or access token in the current session is invalid, an error will be thrown.
-     * @param currentSession The current session that minimally contains an access token and refresh token.
+     * Adopts an externally-provided session into the client.
+     *
+     * Decodes the access token to find its expiry; refreshes immediately when
+     * already expired, otherwise fetches the user info to round-trip the
+     * session. Persists the result and broadcasts `SIGNED_IN`. An invalid
+     * refresh or access token surfaces as `error` on the returned object.
+     *
+     * @param currentSession Minimal session shape — an access token and a
+     *   refresh token. Other fields are recomputed.
+     * @example
+     * ```ts
+     * // After receiving tokens from a custom server-side handoff
+     * await auth.setSession({ access_token, refresh_token })
+     * ```
+     * @see {@link https://faable.com/docs/auth/oidc/userinfo | UserInfo}
      */
     setSession(currentSession: {
         access_token: string;
@@ -184,13 +373,23 @@ export declare class FaableAuthClient extends Base {
     /**
      * Returns the session, refreshing it if necessary.
      *
-     * The session returned can be null if the session is not detected which can happen in the event a user is not signed-in or has logged out.
+     * The session returned can be `null` if no user is signed in or the last
+     * one has logged out.
+     *
+     * **IMPORTANT:** This method loads values directly from the storage
+     * attached to the client. If that storage is based on request cookies (for
+     * example, on the server) the values in it may not be authentic and
+     * therefore it's strongly advised against using this method and its
+     * results in such circumstances — a warning will be emitted when the
+     * storage exposes `isServer: true`. Re-fetch the user with a verified
+     * call (or verify the access token yourself) before trusting it.
      *
-     * **IMPORTANT:** This method loads values directly from the storage attached
-     * to the client. If that storage is based on request cookies for example,
-     * the values in it may not be authentic and therefore it's strongly advised
-     * against using this method and its results in such circumstances. A warning
-     * will be emitted if this is detected. Use {@link #getUser()} instead.
+     * @example
+     * ```ts
+     * const { data, error } = await auth.getSession()
+     * if (data.session) console.log(data.session.user)
+     * ```
+     * @see {@link https://faable.com/docs/auth/oidc/userinfo | UserInfo}
      */
     getSession(): Promise<{
         data: {
@@ -240,12 +439,25 @@ export declare class FaableAuthClient extends Base {
     private _refreshAccessToken;
     private _notifyAllSubscribers;
     /**
-     * Inside a browser context, `signOut()` will remove the logged in user from the browser session and log them out - removing all items from localstorage and then trigger a `"SIGNED_OUT"` event.
+     * Signs the user out and clears the session from storage.
      *
-     * For server-side management, you can revoke all refresh tokens for a user by passing a user's JWT through to `auth.api.signOut(JWT: string)`.
-     * There is no way to revoke a user's access token jwt until it expires. It is recommended to set a shorter expiry on the jwt for this reason.
+     * In a browser context this removes the persisted session and broadcasts a
+     * `SIGNED_OUT` event to every tab listening on the same `storageKey`. The
+     * access token JWT itself remains valid until its `exp` — keep that
+     * expiry short.
      *
-     * If using `others` scope, no `SIGNED_OUT` event is fired!
+     * Scopes:
+     * - `'global'` (default) — invalidate all refresh tokens for the user
+     * - `'local'` — only clear this client's storage
+     * - `'others'` — invalidate every refresh token except this device's; no
+     *   `SIGNED_OUT` event is fired locally
+     *
+     * @example
+     * ```ts
+     * await auth.signOut() // global — all sessions for this user
+     * await auth.signOut({ scope: 'local' }) // only this device
+     * ```
+     * @see {@link https://faable.com/docs/auth/oidc/logout | Logout}
      */
     signOut(options?: SignOut): Promise<{
         error: AuthError | null;
@@ -254,8 +466,28 @@ export declare class FaableAuthClient extends Base {
         error: AuthError | null;
     }>;
     /**
-     * Receive a notification every time an auth event happens.
-     * @param callback A callback function to be invoked when an auth event happens.
+     * Subscribes to auth-state changes for this client.
+     *
+     * The callback fires for `INITIAL_SESSION` once shortly after subscribing
+     * (so consumers don't have to special-case "no event yet"), and then for
+     * every `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `PASSWORD_RECOVERY`,
+     * and `USER_UPDATED` event. Events are broadcast across tabs through
+     * `BroadcastChannel`, so a sign-in or sign-out in one tab reaches every
+     * other tab using the same `storageKey`.
+     *
+     * @param callback Invoked with the event name and the new session (or
+     *   `null` on `SIGNED_OUT`). Can return a promise — the SDK awaits it.
+     * @returns `{ data: { subscription } }` — call `subscription.unsubscribe()`
+     *   to stop listening.
+     * @example
+     * ```ts
+     * const { data: { subscription } } = auth.onAuthStateChange((event, session) => {
+     *   if (event === 'SIGNED_IN') console.log('Welcome', session?.user.email)
+     * })
+     * // later
+     * subscription.unsubscribe()
+     * ```
+     * @see {@link https://faable.com/docs/auth/get-started | Get Started with Faable Auth}
      */
     onAuthStateChange(callback: (event: AuthChangeEvent, session: Session | null) => void | Promise<void>): {
         data: {
@@ -264,10 +496,21 @@ export declare class FaableAuthClient extends Base {
     };
     private _emitInitialSession;
     /**
-     * Returns a new session, regardless of expiry status.
-     * Takes in an optional current session. If not passed in, then refreshSession() will attempt to retrieve it from getSession().
-     * If the current session's refresh token is invalid, an error will be thrown.
-     * @param currentSession The current session. If passed in, it must contain a refresh token.
+     * Forces a new session by exchanging a refresh token regardless of expiry.
+     *
+     * Normally the SDK handles refresh transparently via the auto-refresh
+     * ticker; call this only when you need to force an immediate refresh —
+     * e.g. right after a server-side action that changed the user's claims.
+     * Omit `currentSession` to reuse whatever {@link FaableAuthClient.getSession}
+     * returns.
+     *
+     * @param currentSession Optional session shape carrying the refresh token
+     *   to exchange. When passed it must include `refresh_token`.
+     * @example
+     * ```ts
+     * const { data, error } = await auth.refreshSession()
+     * ```
+     * @see {@link https://faable.com/docs/auth/oauth-flows/refresh-token | Refresh Token}
      */
     refreshSession(currentSession?: {
         refresh_token: string;

package/dist/dts/createClient.d.ts

@@ -1,3 +1,24 @@
 import { FaableAuthClient } from './FaableAuthClient';
 import { FaableAuthClientConfig } from './lib/types';
+/**
+ * Creates a {@link FaableAuthClient} bound to a Faable Auth tenant.
+ *
+ * This is the recommended entry point for app code. The returned client
+ * begins initializing its session in the background as soon as it's created,
+ * so you can start subscribing to events or triggering sign-ins right away.
+ *
+ * @param config Tenant settings. `domain` and `clientId` are required.
+ * @example
+ * ```ts
+ * import { createClient } from '@faable/auth-js'
+ *
+ * export const auth = createClient({
+ *   domain: '<faableauth_domain>',
+ *   clientId: '<client_id>',
+ *   redirectUri: window.location.origin
+ * })
+ * ```
+ * @see {@link https://faable.com/docs/auth/get-started | Get Started with Faable Auth}
+ * @see {@link https://faable.com/docs/auth/clients | Clients}
+ */
 export declare const createClient: (config: FaableAuthClientConfig) => FaableAuthClient;

package/dist/dts/lib/errors.d.ts

@@ -9,7 +9,7 @@ export declare class AuthError extends Error {
      * Error code associated with the error. Most errors coming from
      * HTTP responses will have a code, though some errors that occur
      * before a response is received will not have one present. In that
-     * case {@link #status} will also be undefined.
+     * case {@link AuthError.status} will also be undefined.
      */
     code: ErrorCode | string | undefined;
     /** HTTP status code that caused the error. */

package/dist/dts/lib/nextjs.d.ts

@@ -1,12 +1,36 @@
 import { Session } from './types';
 /**
- * Helper for Next.js (and any other SSR runtime) to read the session from
- * cookies on the server. Mirrors how the browser client builds the storage
- * key and reassembles chunked cookies written by `cookieStorageAdapter`,
- * so the integrator only needs to pass their `clientId`.
+ * Reads the persisted session from cookies on the server.
  *
- * The first argument can be the result of `cookies()` from `next/headers`,
- * or any plain object whose keys are cookie names.
+ * Pair this with the cookie storage adapter on the client: when the browser
+ * stores its session under the cookie shared with the server, the same
+ * `clientId` lets the server reconstruct it. Mirrors how the browser
+ * adapter builds the storage key and reassembles chunked cookies, so no
+ * extra wiring is required.
+ *
+ * @param cookiesStore Either the result of `cookies()` from `next/headers`,
+ *   or any plain `{ name: value }` map. Adapters with a `get(name)` method
+ *   are detected automatically.
+ * @param options `{ clientId, storageKey? }`. `storageKey` defaults to the
+ *   library's built-in prefix — only set it when you customized
+ *   `storageKey` in `createClient`.
+ * @returns The decoded {@link Session} or `null` when the cookie is absent
+ *   or malformed.
+ * @example
+ * ```ts
+ * // app/page.tsx
+ * import { cookies } from 'next/headers'
+ * import { getSessionFromCookies } from '@faable/auth-js'
+ *
+ * export default async function Page() {
+ *   const session = getSessionFromCookies(cookies(), {
+ *     clientId: '<client_id>'
+ *   })
+ *   if (!session) return <SignIn />
+ *   return <Dashboard user={session.user} />
+ * }
+ * ```
+ * @see {@link https://faable.com/docs/auth/quickstart/nextjs | Next.js Quickstart}
  */
 export declare const getSessionFromCookies: (cookiesStore: any, options: {
     clientId: string;

package/dist/dts/lib/storage/cookie-storage.d.ts

@@ -16,16 +16,34 @@ export interface CookieJar {
  */
 export declare const readChunkedCookieValue: (parsed: Map<string, string>, key: string) => string | null;
 /**
- * A storage adapter that uses `document.cookie` to persist sessions. Useful
- * in SSR setups where the server reads the cookie on every request.
+ * Storage adapter that persists the session in `document.cookie`.
  *
- * Values exceeding `MAX_CHUNK_SIZE` are transparently split across numbered
- * cookies (`<key>.0`, `<key>.1`, …) so a full session — which easily exceeds
- * the 4 KB per-cookie browser limit once tokens, id_token and user metadata
- * are encoded — round-trips without being silently dropped by the browser.
+ * Pick this adapter when you need SSR (server reads the cookie on every
+ * request) or want to scope storage with `Secure`, `SameSite`, or `Domain`.
+ * The simplest way to enable it is `createClient({ storage: 'cookie' })` or
+ * by passing `cookieOptions` — the SDK calls this factory internally.
  *
- * The optional `jar` parameter lets tests inject a fake document; production
- * code passes nothing and the adapter uses the real `document` in browsers
- * (and no-ops on the server).
+ * Defaults applied to every cookie: `Path=/`, `SameSite=Lax`, `Secure` on
+ * HTTPS, 30-day `Max-Age`. Override any of them through `options`. Values
+ * larger than the per-cookie browser limit (~4 KB) are transparently split
+ * across numbered chunks (`<key>.0`, `<key>.1`, …) and re-assembled on read.
+ *
+ * @param options Attribute overrides for every written cookie.
+ * @param jar Document-like object whose `cookie` property is read/written.
+ *   Defaults to `document` in browsers and `null` (no-op) on the server —
+ *   only override for tests.
+ * @returns A {@link SupportedStorage} ready to pass to {@link createClient}.
+ * @example
+ * ```ts
+ * import { createClient } from '@faable/auth-js'
+ *
+ * export const auth = createClient({
+ *   domain: '<faableauth_domain>',
+ *   clientId: '<client_id>',
+ *   storage: 'cookie',
+ *   cookieOptions: { domain: '.example.com' }
+ * })
+ * ```
+ * @see {@link https://faable.com/docs/auth/quickstart/nextjs | Next.js Quickstart}
  */
 export declare const cookieStorageAdapter: (options?: CookieOptions, jar?: CookieJar | null) => SupportedStorage;