@cstar.help/js 0.17.5 → 0.18.1

package/README.md

@@ -26,14 +26,14 @@ cStar has one package with separate entry points for different workflows. Start
 | `@cstar.help/js/library`   | Public knowledge base                     | Browser or server | No            | None                     |
 | `@cstar.help/js/community` | Public community forum                    | Browser or server | No            | None                     |
 | `@cstar.help/js/webhook`   | Webhook signature verification            | Server only       | No            | Signing secret           |
-| `@cstar.help/js/auth`      | Authentication utilities                  | Server only       | Yes           | Secret (`sk_*`)          |
+| `@cstar.help/js/auth`      | Customer signup and login                 | Browser           | No            | None (`teamSlug`)        |
 
 ### The Security Model
 
 The server API and customer chat authenticate differently:
 
 - **Secret API keys** (`sk_live_*`, `sk_test_*`) authorize team API operations within the key's permissions. Keep them on your server.
-- **Publishable API keys** (`pk_live_*`, `pk_test_*`) provide limited read-only access to API endpoints that accept them. They do not identify a customer or authorize customer chat.
+- **Publishable API keys** (`pk_live_*`, `pk_test_*`) are for the public SDKs (`LibraryClient`, `CommunityClient`) and `GET /auth/whoami`. Team API endpoints refuse them with 403: `publishable_key_forbidden` on reads and `publishable_key_write` on writes, so `CStarClient` needs a secret key. They do not identify a customer or authorize customer chat.
 - **ChatClient** takes a `teamSlug`, then authenticates a customer through HMAC identity verification or a customer session. It has no API-key option. Keep HMAC signing secrets on your server too.
 
 > Building a support dashboard? Use `CStarClient` on your backend. Adding a conversation to your website? Use `ChatClient` and one of the customer authentication options below.
@@ -90,7 +90,7 @@ The `isInternal` boolean is also accepted when creating a note. If you supply bo
 
 ### Full Resource Reference
 
-**Core Resources** — Tickets, customers, and knowledge base.
+**Core Resources**: Tickets, customers, and knowledge base.
 
 | Resource                 | Methods                                                                                         |
 | ------------------------ | ----------------------------------------------------------------------------------------------- |
@@ -100,7 +100,7 @@ The `isInternal` boolean is also accepted when creating a note. If you supply bo
 | `cstar.articles`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
 | `cstar.categories`       | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                         |
 
-**Team & Configuration** — Members, settings, and customization.
+**Team & Configuration**: Members, settings, and customization.
 
 | Resource                      | Methods                                                                                                                |
 | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -110,9 +110,9 @@ The `isInternal` boolean is also accepted when creating a note. If you supply bo
 | `cstar.settings.statuses`     | `.list()` `.create(params)` `.update(key, params)` `.del(key)` `.reorder(keys)`                                        |
 | `cstar.settings.quickReplies` | `.list()` `.create(params)` `.update(id, params)` `.del(id)` `.reorder(ids)`                                           |
 | `cstar.customFields`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.reorder(ids)`                                |
-| `cstar.notifications`         | `.list()` `.unreadCount()` `.markRead(id)` `.markAllRead()`                                                            |
+| `cstar.notifications`         | `.list({ userId })` `.unreadCount(userId)` `.markRead(id, userId)` `.markAllRead(userId)`                              |
 
-**Operations** — Analytics, bulk actions, and data management.
+**Operations**: Analytics, bulk actions, and data management.
 
 | Resource               | Methods                                                                                 |
 | ---------------------- | --------------------------------------------------------------------------------------- |
@@ -127,7 +127,7 @@ The `isInternal` boolean is also accepted when creating a note. If you supply bo
 | `cstar.auditLog`       | `.list(params?)`                                                                        |
 | `cstar.customerGroups` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)`                 |
 
-**Gamification** — The full game system.
+**Gamification**: The full game system.
 
 | Resource                  | Methods                                                                                             |
 | ------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -144,9 +144,9 @@ The `isInternal` boolean is also accepted when creating a note. If you supply bo
 
 Game writes belong on your server with a secret API key. Use user and team UUIDs from cStar. One-ups and high fives default their sender to the key creator. Puzzle scoreboards require a `puzzleId`; streak boards use `{ type: 'streaks' }`. Cosmetic lists require a `userId`.
 
-Cosmetic and season lists return `{ data, pagination, hasMore }`. One-up and high-five lists return `{ object: 'list', data }`. Today's quests return `{ quests, completedToday, totalQuests, allComplete, completionBonus, resetsAt }`. Single resources return bare objects.
+Cosmetic and season lists return `{ data, pagination, hasMore }`. One-up and high-five lists return `{ object: 'list', data }`. Today's quests return `{ quests, completedToday, totalQuests, allComplete, resetsAt }` (each quest pays its own `xpReward` and `goldReward`; there is no all-quests bonus). Single resources return bare objects.
 
-**Advanced** — AI, automations, views, billing, webhooks.
+**Advanced**: AI, automations, views, billing, webhooks.
 
 | Resource                 | Methods                                                                                                                                                                            |
 | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -199,9 +199,9 @@ const csv = await cstar.export.create({ resources: ['tickets'], format: 'csv' })
 
 // Saved views
 const view = await cstar.views.create({
-	name: 'Urgent Unresolved',
+	name: 'Critical Unresolved',
 	entityType: 'tickets',
-	filters: { priority: 'urgent', status: 'open' }
+	filters: { priority: 'critical', status: 'open' }
 });
 const { data: results } = await cstar.views.execute(view.id);
 
@@ -304,7 +304,9 @@ function closeChat() {
 
 HTTP and network failures use typed subclasses of `ChatClientError`. A server response may provide a `requestId` through the `X-Request-Id` header; it is `null` when unavailable. Other failures, such as malformed response JSON, can still throw ordinary errors.
 
-A lost response may follow a successful send. Keep the unsent text available and check the conversation before offering another send. Do not automatically resend a message because a network or server error occurred.
+Customer message sends generate a new retry key for each intentional reply and retry network or server failures at most twice. Each retry uses the same key and returns the original saved reply. A terminal `ChatClientError` retains that key in `error.idempotencyKey`. Reuse it with `chat.messages.send(ticketId, content, { idempotencyKey })` for a manual retry of the same reply. Keep the draft and key together; use a new key when the message or ticket changes. Receipts last 24 hours and stay scoped to the customer, team and live/test mode.
+
+Pass `{ signal }` to cancel a send or its retry delay. For a cancellable UI, generate and retain your own `idempotencyKey` before sending. A cancelled request may already have been saved. Conversation history includes `client_request_key` so your UI can reconcile a pending bubble with its confirmed reply. Separate sends with identical text remain separate messages. These message retries do not apply to ticket creation or other customer writes.
 
 ```typescript
 import {
@@ -338,7 +340,7 @@ try {
 
 ## Client-Side: Public Knowledge Base
 
-Search and browse your public help center — **no authentication required**.
+Search and browse your public help center. **No authentication required**.
 
 ```typescript
 import { LibraryClient } from '@cstar.help/js/library';
@@ -354,7 +356,7 @@ const article = await library.article('how-to-reset-password');
 
 ## Client-Side: Public Community
 
-Browse your public community forum — **no authentication required**.
+Browse your public community forum. **No authentication required**.
 
 ```typescript
 import { CommunityClient } from '@cstar.help/js/community';
@@ -373,17 +375,17 @@ const { post, comments } = await community.post('dark-mode-support');
 Verify incoming webhook signatures on your server.
 
 ```typescript
-import { constructEvent } from '@cstar.help/js/webhook';
+import { constructEvent } from '@cstar.help/js/webhook/node';
 
-// In your webhook handler
+// In your webhook handler (Node). It throws if the signature is invalid.
 const event = constructEvent(rawBody, signature, 'whsec_your_secret');
 
 switch (event.type) {
 	case 'ticket.created':
-		console.log('New ticket:', event.data.title);
+		console.log('New ticket:', event.data.ticket.title);
 		break;
 	case 'customer.created':
-		console.log('New customer:', event.data.email);
+		console.log('New customer:', event.data.customer.email);
 		break;
 }
 ```
@@ -401,12 +403,12 @@ const event = await constructEventAsync(rawBody, signature, secret);
 
 ```typescript
 const cstar = new CStarClient({
-	apiKey: 'sk_live_...', // Required — must be a secret key (sk_*)
-	teamId: 'tm_...', // Required — your team ID
-	baseUrl: 'https://...', // Optional — defaults to https://www.cstar.help
-	version: '2026-03-01', // Optional — API version header
-	maxRetries: 3, // Optional — retry attempts for retry-safe failures and 429
-	timeout: 30000 // Optional — request timeout in ms
+	apiKey: 'sk_live_...', // Required: must be a secret key (sk_*)
+	teamId: 'tm_...', // Required: your team ID
+	baseUrl: 'https://...', // Optional: defaults to https://www.cstar.help
+	version: '2026-03-01', // Optional: API version header
+	maxRetries: 3, // Optional: retry attempts for retry-safe failures and 429
+	timeout: 30000 // Optional: request timeout in ms
 });
 ```
 
@@ -434,7 +436,7 @@ const cstar = new CStarClient({
 });
 
 console.log(cstar.isTestMode); // true
-// All operations use test data — no real customers affected
+// All operations use test data, so no real customers are affected
 ```
 
 ## Error Handling
@@ -478,6 +480,22 @@ const ticket = await cstar.tickets.create(
 );
 ```
 
+For 24 hours, the same request with the same key returns the first successful
+response. The same key with a different body throws `CStarValidationError`
+(`idempotency_key_reused`, 422). While the first request is still running, the
+API answers `409 idempotency_key_in_use` with `Retry-After`. From 0.18.1
+(unreleased), the client waits and retries within `maxRetries`; 0.18.0 throws
+`CStarConflictError`.
+
+The API ignores the key on `webhooks.create`, `webhooks.listen` and
+`export.create`, so a key does not make their retries safe: the client still
+retries a network error or 5xx. Leave the key off those calls (without one the
+client does not retry them), or use a client with `maxRetries: 0`. Check
+`webhooks.list()` before you retry `webhooks.create`. A repeated `export.create`
+only reads your data again (nothing is stored). A repeated `webhooks.listen` is a
+second CLI listener: remove it with `webhooks.unlisten(id)`, or it is swept after
+5 minutes without a heartbeat.
+
 ## Requirements
 
 - Node.js 22+ (matching the supported Supabase dependency)

package/dist/auth/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/auth/index.ts
@@ -308,45 +318,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.
    *
@@ -370,9 +531,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() {
@@ -390,6 +560,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, {

package/dist/auth/index.d.cts

@@ -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;
 }