@cstar.help/js 0.17.5 → 0.18.1

package/dist/auth/index.d.ts

@@ -6,6 +6,14 @@ interface AuthConfig {
     teamSlug: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
+    /**
+     * Supabase project URL used to send the signup confirmation email.
+     * Defaults to cStar's production project. Required when `baseUrl` points
+     * anywhere other than production, so the email comes from the same project.
+     */
+    supabaseUrl?: string;
+    /** Supabase publishable (anon) key that pairs with `supabaseUrl`. */
+    supabaseKey?: string;
 }
 /** A customer identity returned from auth endpoints. */
 interface AuthCustomer {
@@ -17,26 +25,33 @@ interface AuthCustomer {
 interface SignupParams {
     /** Customer email address. */
     email: string;
-    /** Password (minimum 6 characters). */
-    password: string;
     /** Customer display name. */
     name?: string;
+    /**
+     * Page the confirmation link returns to. Defaults to the current page in a
+     * browser. Its origin must be on the team's allowed redirect list, or cStar
+     * falls back to the hosted widget page.
+     */
+    returnUrl?: string;
 }
-/** Response from a successful signup. */
+/**
+ * Response from signup. It is identical for new and existing emails, so a
+ * signup form cannot be used to discover who already has an account. The
+ * customer confirms through the emailed link; call `completeSignIn()` on the
+ * page the link returns to.
+ */
 interface SignupResult {
-    customer: AuthCustomer;
-    /** Access token for authenticated requests. Null if email confirmation is required. */
-    accessToken: string | null;
-    /** Refresh token for renewing the session. Null if email confirmation is required. */
-    refreshToken: string | null;
-}
-/** Response when email confirmation is required after signup. */
-interface SignupConfirmationResult {
     success: true;
     message: string;
     requiresConfirmation: true;
 }
-/** Parameters for logging in an existing customer. */
+/** @deprecated Signup always requires confirmation now. Use `SignupResult`. */
+type SignupConfirmationResult = SignupResult;
+/**
+ * Parameters for logging in an existing customer. Signup is password-less,
+ * so this works only after the customer has chosen a password (see
+ * `AuthClient.setPassword()`).
+ */
 interface LoginParams {
     /** Customer email address. */
     email: string;
@@ -69,47 +84,83 @@ interface AuthSession {
  *
  * const auth = new AuthClient({ teamSlug: 'acme' });
  *
- * // Sign up a new customer
- * const result = await auth.signup({
- *   email: 'jane@example.com',
- *   password: 'securepass123',
- *   name: 'Jane Doe',
- * });
+ * // Sign up: cStar emails a sign-in link. No password yet.
+ * await auth.signup({ email: 'jane@example.com', name: 'Jane Doe' });
  *
- * // Log in an existing customer
- * const session = await auth.login({
- *   email: 'jane@example.com',
- *   password: 'securepass123',
- * });
+ * // On the page the link returns to
+ * const session = await auth.completeSignIn();
  *
- * // Check current session
- * const current = auth.getSession();
+ * // Optional: choose a password for faster sign-in next time
+ * await auth.setPassword('securepass123');
+ *
+ * // Later visits: log in with that password
+ * await auth.login({ email: 'jane@example.com', password: 'securepass123' });
  * ```
  */
 declare class AuthClient {
     private readonly baseUrl;
     private readonly teamSlug;
+    private readonly supabaseUrl;
+    private readonly supabaseKey;
     private session;
+    private pkceClient;
     constructor(config: AuthConfig);
     /**
-     * Create a new customer account.
+     * Create a password-less customer account and email a sign-in link.
+     *
+     * The response is the same whether or not the email already has an
+     * account. Nothing is signed in yet: the customer clicks the link, and the
+     * page it returns to calls `completeSignIn()`. Signup takes no password,
+     * because one chosen before the link proves the address could belong to
+     * someone else. Once signed in, the customer can call `setPassword()` to
+     * enable `login()`.
      *
-     * If the team requires email confirmation, returns a `SignupConfirmationResult`
-     * instead of tokens. Check for `requiresConfirmation` in the response.
+     * Runs in a browser: the PKCE verifier is stored in this page's
+     * localStorage so `completeSignIn()` can finish the exchange.
      *
-     * @throws Error on validation failure, duplicate email, or server error
+     * @throws CStarRateLimitError when too many signups were attempted
      */
-    signup(params: SignupParams): Promise<SignupResult | SignupConfirmationResult>;
+    signup(params: SignupParams): Promise<SignupResult>;
+    /**
+     * Finish sign-in on the page the confirmation link returns to.
+     *
+     * Reads `?code=` and `?type=` from the URL, removes them from the address
+     * bar, exchanges the code, and stores the session. Returns null when the URL
+     * holds no cStar confirmation code or the exchange fails.
+     *
+     * @param url Defaults to `window.location.href`.
+     */
+    completeSignIn(url?: string): Promise<AuthSession | null>;
+    /**
+     * Choose a password for the signed-in customer, so later visits can use
+     * `login()` instead of an emailed link.
+     *
+     * Needs a session from `completeSignIn()` or `login()`. This is the same
+     * Supabase Auth password update the hosted widget makes after a first
+     * email sign-in, and it clears the widget's "choose a password" prompt.
+     * The customer stays signed in.
+     *
+     * @throws CStarValidationError when the password is under 8 characters or is rejected
+     * @throws CStarAuthenticationError when there is no session or it has expired
+     */
+    setPassword(password: string): Promise<void>;
     /**
      * Log in an existing customer with email and password.
      *
+     * Signup is password-less, so this works only after the customer has
+     * chosen a password with `setPassword()` or in the hosted widget.
+     *
      * On success, stores the session internally so subsequent
      * ChatClient requests can use `auth.getSession()` for tokens.
      *
      * @throws Error on invalid credentials, unconfirmed email, or server error
      */
     login(params: LoginParams): Promise<LoginResult>;
-    /** Clear the stored session. */
+    /**
+     * Clear the session: the in-memory one and, when a sign-in link or
+     * setPassword() restored it through Supabase Auth, the copy that client
+     * keeps in browser storage, so the next person on the device is signed out.
+     */
     logout(): void;
     /** Get the current session, or null if not authenticated. */
     getSession(): AuthSession | null;
@@ -119,6 +170,7 @@ declare class AuthClient {
     get isAuthenticated(): boolean;
     /** Get the current access token, or null. Useful for passing to ChatClient. */
     get accessToken(): string | null;
+    private getPkceClient;
     private fetch;
 }
 

package/dist/auth/index.js

@@ -269,45 +269,196 @@ function parseError(statusCode, body, retryAfter) {
 
 // src/auth/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
+var PRODUCTION_ORIGINS = /* @__PURE__ */ new Set(["https://www.cstar.help", "https://cstar.help"]);
+var PRODUCTION_SUPABASE_URL = "https://kmorvgcubqthkfrasbny.supabase.co";
+var PRODUCTION_SUPABASE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Imttb3J2Z2N1YnF0aGtmcmFzYm55Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjUzMzczNjIsImV4cCI6MjA4MDkxMzM2Mn0.e0RJbMpZr-8FbJmAGhdw86Ym9M4MCfvX9Qm6Va3d_N8";
+var PKCE_STORAGE_KEY = "cstar_widget_pkce";
+var MIN_PASSWORD_LENGTH = 8;
+var CONFIRMATION_TYPES = /* @__PURE__ */ new Set(["magiclink", "signup", "recovery"]);
 var AuthClient = class {
   constructor(config) {
     this.session = null;
+    this.pkceClient = null;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.teamSlug = config.teamSlug;
+    const isProduction = PRODUCTION_ORIGINS.has(this.baseUrl);
+    this.supabaseUrl = config.supabaseUrl ?? (isProduction ? PRODUCTION_SUPABASE_URL : null);
+    this.supabaseKey = config.supabaseKey ?? (isProduction ? PRODUCTION_SUPABASE_KEY : null);
   }
   /**
-   * Create a new customer account.
+   * Create a password-less customer account and email a sign-in link.
    *
-   * If the team requires email confirmation, returns a `SignupConfirmationResult`
-   * instead of tokens. Check for `requiresConfirmation` in the response.
+   * The response is the same whether or not the email already has an
+   * account. Nothing is signed in yet: the customer clicks the link, and the
+   * page it returns to calls `completeSignIn()`. Signup takes no password,
+   * because one chosen before the link proves the address could belong to
+   * someone else. Once signed in, the customer can call `setPassword()` to
+   * enable `login()`.
    *
-   * @throws Error on validation failure, duplicate email, or server error
+   * Runs in a browser: the PKCE verifier is stored in this page's
+   * localStorage so `completeSignIn()` can finish the exchange.
+   *
+   * @throws CStarRateLimitError when too many signups were attempted
    */
   async signup(params) {
-    const response = await this.fetch(
-      "/api/widget/auth/signup",
-      {
-        method: "POST",
-        body: {
-          teamId: this.teamSlug,
-          email: params.email,
-          password: params.password,
-          name: params.name
-        }
+    const returnUrl = params.returnUrl ?? (typeof window !== "undefined" && window.location ? window.location.href : void 0);
+    const prepared = await this.fetch("/api/widget/auth/signup", {
+      method: "POST",
+      body: {
+        teamId: this.teamSlug,
+        email: params.email,
+        name: params.name,
+        returnUrl
       }
-    );
-    if ("accessToken" in response && response.accessToken && response.customer) {
+    });
+    if (!prepared?.emailRedirectTo) {
+      throw parsePublicError(500, null, "Sign-up prepare returned no redirect URL.");
+    }
+    const client = await this.getPkceClient();
+    const { error } = await client.auth.signInWithOtp({
+      email: params.email,
+      options: { emailRedirectTo: prepared.emailRedirectTo, shouldCreateUser: false }
+    });
+    if (error) {
+      if (error.status === 429) {
+        throw parsePublicError(
+          429,
+          { error: "Too many sign-up requests. Please wait a few minutes and try again." },
+          "Too many sign-up requests"
+        );
+      }
+      throw parsePublicError(
+        502,
+        {
+          error: "Couldn't send a confirmation email. Try again, or sign in if you already have an account."
+        },
+        "Confirmation email failed"
+      );
+    }
+    return {
+      success: true,
+      message: prepared.message ?? "Check your inbox to finish signing up.",
+      requiresConfirmation: true
+    };
+  }
+  /**
+   * Finish sign-in on the page the confirmation link returns to.
+   *
+   * Reads `?code=` and `?type=` from the URL, removes them from the address
+   * bar, exchanges the code, and stores the session. Returns null when the URL
+   * holds no cStar confirmation code or the exchange fails.
+   *
+   * @param url Defaults to `window.location.href`.
+   */
+  async completeSignIn(url) {
+    const href = url ?? (typeof window !== "undefined" && window.location ? window.location.href : null);
+    if (!href) return null;
+    const parsed = new URL(href);
+    const code = parsed.searchParams.get("code");
+    const type = parsed.searchParams.get("type");
+    if (!code || !type || !CONFIRMATION_TYPES.has(type)) return null;
+    if (url === void 0 && typeof window !== "undefined" && window.history?.replaceState) {
+      parsed.searchParams.delete("code");
+      parsed.searchParams.delete("type");
+      try {
+        window.history.replaceState(null, "", parsed.pathname + parsed.search + parsed.hash);
+      } catch {
+      }
+    }
+    const client = await this.getPkceClient();
+    const exchanged = await client.auth.exchangeCodeForSession(code);
+    const supabaseSession = exchanged?.data?.session;
+    if (exchanged?.error || !supabaseSession) return null;
+    const result = await this.fetch("/api/widget/auth/magic-link/exchange", {
+      method: "POST",
+      body: {
+        teamId: this.teamSlug,
+        accessToken: supabaseSession.access_token,
+        refreshToken: supabaseSession.refresh_token
+      }
+    });
+    if (!result.customer || !result.accessToken || !result.refreshToken) return null;
+    this.session = {
+      customer: result.customer,
+      accessToken: result.accessToken,
+      refreshToken: result.refreshToken
+    };
+    return this.session;
+  }
+  /**
+   * Choose a password for the signed-in customer, so later visits can use
+   * `login()` instead of an emailed link.
+   *
+   * Needs a session from `completeSignIn()` or `login()`. This is the same
+   * Supabase Auth password update the hosted widget makes after a first
+   * email sign-in, and it clears the widget's "choose a password" prompt.
+   * The customer stays signed in.
+   *
+   * @throws CStarValidationError when the password is under 8 characters or is rejected
+   * @throws CStarAuthenticationError when there is no session or it has expired
+   */
+  async setPassword(password) {
+    if (!password || password.length < MIN_PASSWORD_LENGTH) {
+      throw parsePublicError(
+        400,
+        { error: `Password must be at least ${MIN_PASSWORD_LENGTH} characters` },
+        "Invalid password"
+      );
+    }
+    const current = this.session;
+    if (!current) {
+      throw parsePublicError(
+        401,
+        { error: "Sign in before choosing a password." },
+        "Not signed in"
+      );
+    }
+    const client = await this.getPkceClient();
+    const restored = await client.auth.setSession({
+      access_token: current.accessToken,
+      refresh_token: current.refreshToken
+    });
+    const restoredSession = restored?.data?.session;
+    if (restored?.error || !restoredSession) {
+      throw parsePublicError(
+        401,
+        { error: "Your session has expired. Sign in again to choose a password." },
+        "Session expired"
+      );
+    }
+    if (this.session === current) {
       this.session = {
-        customer: response.customer,
-        accessToken: response.accessToken,
-        refreshToken: response.refreshToken
+        ...current,
+        accessToken: restoredSession.access_token,
+        refreshToken: restoredSession.refresh_token
       };
     }
-    return response;
+    const { error } = await client.auth.updateUser({
+      password,
+      data: { widget_password_pending: false }
+    });
+    if (error) {
+      if (error.status === 429) {
+        throw parsePublicError(
+          429,
+          { error: "Too many password changes. Please wait a few minutes and try again." },
+          "Too many password changes"
+        );
+      }
+      const rejected = error.status === 400 || error.status === 422;
+      throw parsePublicError(
+        rejected ? 400 : 502,
+        { error: "That password could not be saved. Please try another one." },
+        "Password not saved"
+      );
+    }
   }
   /**
    * Log in an existing customer with email and password.
    *
+   * Signup is password-less, so this works only after the customer has
+   * chosen a password with `setPassword()` or in the hosted widget.
+   *
    * On success, stores the session internally so subsequent
    * ChatClient requests can use `auth.getSession()` for tokens.
    *
@@ -331,9 +482,18 @@ var AuthClient = class {
     }
     return response;
   }
-  /** Clear the stored session. */
+  /**
+   * Clear the session: the in-memory one and, when a sign-in link or
+   * setPassword() restored it through Supabase Auth, the copy that client
+   * keeps in browser storage, so the next person on the device is signed out.
+   */
   logout() {
     this.session = null;
+    const pkceClient = this.pkceClient;
+    if (pkceClient) {
+      void pkceClient.then((client) => client.auth.signOut({ scope: "local" })).catch(() => {
+      });
+    }
   }
   /** Get the current session, or null if not authenticated. */
   getSession() {
@@ -351,6 +511,35 @@ var AuthClient = class {
   get accessToken() {
     return this.session?.accessToken ?? null;
   }
+  getPkceClient() {
+    const { supabaseUrl, supabaseKey } = this;
+    if (!supabaseUrl || !supabaseKey) {
+      return Promise.reject(
+        parsePublicError(
+          400,
+          {
+            error: "AuthClient needs supabaseUrl and supabaseKey when baseUrl is not https://www.cstar.help."
+          },
+          "Missing Supabase config"
+        )
+      );
+    }
+    this.pkceClient ?? (this.pkceClient = import(
+      /* webpackIgnore: true */
+      "@supabase/supabase-js"
+    ).then(
+      ({ createClient }) => createClient(supabaseUrl, supabaseKey, {
+        auth: {
+          flowType: "pkce",
+          persistSession: true,
+          autoRefreshToken: false,
+          storageKey: PKCE_STORAGE_KEY,
+          detectSessionInUrl: false
+        }
+      })
+    ));
+    return this.pkceClient;
+  }
   async fetch(path, options) {
     const url = `${this.baseUrl}${path}`;
     const response = await globalThis.fetch(url, {