@cstar.help/js 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cStar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -23,8 +23,8 @@ Manage tickets, customers, articles, and webhooks with your secret API key.
 import { CStarClient } from '@cstar.help/js';
 
 const cstar = new CStarClient({
-  apiKey: 'sk_live_abc123...',
-  teamId: 'tm_your_team_id',
+	apiKey: 'sk_live_abc123...',
+	teamId: 'tm_your_team_id'
 });
 
 // List open tickets
@@ -32,8 +32,8 @@ const { data: tickets } = await cstar.tickets.list({ status: 'open' });
 
 // Create a ticket
 const { data: ticket } = await cstar.tickets.create({
-  title: 'Help with billing',
-  customerId: 'cus_abc123',
+	title: 'Help with billing',
+	customerId: 'cus_abc123'
 });
 
 // Get a customer with expanded fields
@@ -41,7 +41,7 @@ const { data: customer } = await cstar.customers.get('cus_abc123');
 
 // Auto-paginate through all tickets
 for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' })) {
-  console.log(ticket.title);
+	console.log(ticket.title);
 }
 ```
 
@@ -56,8 +56,8 @@ const chat = new ChatClient({ teamSlug: 'acme' });
 
 // Identify the customer (HMAC signature from your server)
 await chat.identify(
-  { externalId: 'usr_123', email: 'jane@example.com', name: 'Jane', timestamp: Date.now() / 1000 },
-  hmacSignature
+	{ externalId: 'usr_123', email: 'jane@example.com', name: 'Jane', timestamp: Date.now() / 1000 },
+	hmacSignature
 );
 
 // List conversations
@@ -68,7 +68,7 @@ await chat.messages.send('tkt_abc123', 'Thanks for the help!');
 
 // Subscribe to new messages (polling)
 const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
-  console.log(`${message.sender_name}: ${message.content}`);
+	console.log(`${message.sender_name}: ${message.content}`);
 });
 
 // Clean up
@@ -105,12 +105,12 @@ import { constructEvent } from '@cstar.help/js/webhook';
 const event = constructEvent(rawBody, signature, 'whsec_your_secret');
 
 switch (event.type) {
-  case 'ticket.created':
-    console.log('New ticket:', event.data.title);
-    break;
-  case 'customer.created':
-    console.log('New customer:', event.data.email);
-    break;
+	case 'ticket.created':
+		console.log('New ticket:', event.data.title);
+		break;
+	case 'customer.created':
+		console.log('New customer:', event.data.email);
+		break;
 }
 ```
 
@@ -126,24 +126,24 @@ const event = await constructEventAsync(rawBody, signature, secret);
 
 ### CStarClient
 
-| Resource | Methods |
-|----------|---------|
-| `cstar.tickets` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)` |
-| `cstar.customers` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.articles` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.webhooks` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)` |
+| Resource                 | Methods                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `cstar.tickets`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)`                                                   |
+| `cstar.customers`        | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.articles`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.webhooks`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)`             |
 
 ### Configuration
 
 ```typescript
 const cstar = new CStarClient({
-  apiKey: 'sk_live_...',    // Required — secret or publishable key
-  teamId: 'tm_...',         // Required — your team ID
-  baseUrl: 'https://...',   // Optional — defaults to https://app.cstar.help
-  version: '2026-03-01',    // Optional — API version header
-  maxRetries: 3,            // Optional — retry attempts for 5xx/429
-  timeout: 30000,           // Optional — request timeout in ms
+	apiKey: 'sk_live_...', // Required — secret or publishable key
+	teamId: 'tm_...', // Required — your team ID
+	baseUrl: 'https://...', // Optional — defaults to https://app.cstar.help
+	version: '2026-03-01', // Optional — API version header
+	maxRetries: 3, // Optional — retry attempts for 5xx/429
+	timeout: 30000 // Optional — request timeout in ms
 });
 ```
 
@@ -154,8 +154,8 @@ Test mode is auto-detected from your API key prefix:
 ```typescript
 // Uses test data — no real customers affected
 const cstar = new CStarClient({
-  apiKey: 'sk_test_abc123...',
-  teamId: 'tm_your_team_id',
+	apiKey: 'sk_test_abc123...',
+	teamId: 'tm_your_team_id'
 });
 
 console.log(cstar.isTestMode); // true
@@ -169,15 +169,15 @@ All API errors throw typed exceptions:
 import { CStarError, CStarNotFoundError, CStarValidationError } from '@cstar.help/js';
 
 try {
-  await cstar.tickets.get('tkt_nonexistent');
+	await cstar.tickets.get('tkt_nonexistent');
 } catch (err) {
-  if (err instanceof CStarNotFoundError) {
-    console.log('Ticket not found:', err.message);
-  } else if (err instanceof CStarValidationError) {
-    console.log('Invalid param:', err.param);
-  } else if (err instanceof CStarError) {
-    console.log('API error:', err.code, err.statusCode);
-  }
+	if (err instanceof CStarNotFoundError) {
+		console.log('Ticket not found:', err.message);
+	} else if (err instanceof CStarValidationError) {
+		console.log('Invalid param:', err.param);
+	} else if (err instanceof CStarError) {
+		console.log('API error:', err.code, err.statusCode);
+	}
 }
 ```
 
@@ -187,8 +187,8 @@ Safely retry create operations:
 
 ```typescript
 const { data: ticket } = await cstar.tickets.create(
-  { title: 'Billing issue', customerId: 'cus_abc' },
-  { idempotencyKey: 'create-billing-issue-usr123' }
+	{ title: 'Billing issue', customerId: 'cus_abc' },
+	{ idempotencyKey: 'create-billing-issue-usr123' }
 );
 ```
 

package/dist/auth/index.cjs

@@ -0,0 +1,127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/auth/index.ts
+var auth_exports = {};
+__export(auth_exports, {
+  AuthClient: () => AuthClient
+});
+module.exports = __toCommonJS(auth_exports);
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var AuthClient = class {
+  constructor(config) {
+    this.session = null;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+  }
+  /**
+   * Create a new customer account.
+   *
+   * If the team requires email confirmation, returns a `SignupConfirmationResult`
+   * instead of tokens. Check for `requiresConfirmation` in the response.
+   *
+   * @throws Error on validation failure, duplicate email, or server error
+   */
+  async signup(params) {
+    const response = await this.fetch(
+      "/widget/api/auth/signup",
+      {
+        method: "POST",
+        body: {
+          team_id: this.teamSlug,
+          email: params.email,
+          password: params.password,
+          name: params.name
+        }
+      }
+    );
+    if ("access_token" in response && response.access_token && response.customer) {
+      this.session = {
+        customer: response.customer,
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token
+      };
+    }
+    return response;
+  }
+  /**
+   * Log in an existing customer with email and password.
+   *
+   * 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
+   */
+  async login(params) {
+    const response = await this.fetch("/widget/api/auth/login", {
+      method: "POST",
+      body: {
+        team_id: this.teamSlug,
+        email: params.email,
+        password: params.password
+      }
+    });
+    if (response.access_token && response.customer) {
+      this.session = {
+        customer: response.customer,
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token
+      };
+    }
+    return response;
+  }
+  /** Clear the stored session. */
+  logout() {
+    this.session = null;
+  }
+  /** Get the current session, or null if not authenticated. */
+  getSession() {
+    return this.session;
+  }
+  /** Get the authenticated customer, or null if not logged in. */
+  getCustomer() {
+    return this.session?.customer ?? null;
+  }
+  /** Whether a customer is currently authenticated. */
+  get isAuthenticated() {
+    return this.session !== null;
+  }
+  /** Get the current access token, or null. Useful for passing to ChatClient. */
+  get accessToken() {
+    return this.session?.accessToken ?? null;
+  }
+  async fetch(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await globalThis.fetch(url, {
+      method: options.method,
+      headers: { "Content-Type": "application/json" },
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: "Request failed" }));
+      const message = errorBody.error ?? errorBody.message ?? `Auth API error: ${response.status}`;
+      throw new Error(message);
+    }
+    return response.json();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthClient
+});

package/dist/auth/index.d.cts

@@ -0,0 +1,123 @@
+/** Configuration for the AuthClient. */
+interface AuthConfig {
+    /** Team slug (e.g., 'acme'). Identifies which team's customers to authenticate. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+}
+/** A customer identity returned from auth endpoints. */
+interface AuthCustomer {
+    id: string;
+    email: string;
+    name: string;
+}
+/** Parameters for signing up a new customer. */
+interface SignupParams {
+    /** Customer email address. */
+    email: string;
+    /** Password (minimum 6 characters). */
+    password: string;
+    /** Customer display name. */
+    name?: string;
+}
+/** Response from a successful signup. */
+interface SignupResult {
+    customer: AuthCustomer;
+    /** Access token for authenticated requests. Null if email confirmation is required. */
+    access_token: string | null;
+    /** Refresh token for renewing the session. Null if email confirmation is required. */
+    refresh_token: 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. */
+interface LoginParams {
+    /** Customer email address. */
+    email: string;
+    /** Customer password. */
+    password: string;
+}
+/** Response from a successful login. */
+interface LoginResult {
+    customer: AuthCustomer;
+    /** Access token for authenticated requests. */
+    access_token: string | null;
+    /** Refresh token for renewing the session. */
+    refresh_token: string | null;
+}
+/** Stored session with tokens and customer identity. */
+interface AuthSession {
+    customer: AuthCustomer;
+    accessToken: string;
+    refreshToken: string;
+}
+
+/**
+ * Customer authentication client for the cStar widget API.
+ *
+ * Provides signup, login, and session management for end-customers
+ * interacting with your support widget or custom integration.
+ *
+ * ```typescript
+ * import { AuthClient } from '@cstar.help/js/auth';
+ *
+ * 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',
+ * });
+ *
+ * // Log in an existing customer
+ * const session = await auth.login({
+ *   email: 'jane@example.com',
+ *   password: 'securepass123',
+ * });
+ *
+ * // Check current session
+ * const current = auth.getSession();
+ * ```
+ */
+declare class AuthClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private session;
+    constructor(config: AuthConfig);
+    /**
+     * Create a new customer account.
+     *
+     * If the team requires email confirmation, returns a `SignupConfirmationResult`
+     * instead of tokens. Check for `requiresConfirmation` in the response.
+     *
+     * @throws Error on validation failure, duplicate email, or server error
+     */
+    signup(params: SignupParams): Promise<SignupResult | SignupConfirmationResult>;
+    /**
+     * Log in an existing customer with email and password.
+     *
+     * 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. */
+    logout(): void;
+    /** Get the current session, or null if not authenticated. */
+    getSession(): AuthSession | null;
+    /** Get the authenticated customer, or null if not logged in. */
+    getCustomer(): AuthCustomer | null;
+    /** Whether a customer is currently authenticated. */
+    get isAuthenticated(): boolean;
+    /** Get the current access token, or null. Useful for passing to ChatClient. */
+    get accessToken(): string | null;
+    private fetch;
+}
+
+export { AuthClient, type AuthConfig, type AuthCustomer, type AuthSession, type LoginParams, type LoginResult, type SignupConfirmationResult, type SignupParams, type SignupResult };

package/dist/auth/index.d.ts

@@ -0,0 +1,123 @@
+/** Configuration for the AuthClient. */
+interface AuthConfig {
+    /** Team slug (e.g., 'acme'). Identifies which team's customers to authenticate. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+}
+/** A customer identity returned from auth endpoints. */
+interface AuthCustomer {
+    id: string;
+    email: string;
+    name: string;
+}
+/** Parameters for signing up a new customer. */
+interface SignupParams {
+    /** Customer email address. */
+    email: string;
+    /** Password (minimum 6 characters). */
+    password: string;
+    /** Customer display name. */
+    name?: string;
+}
+/** Response from a successful signup. */
+interface SignupResult {
+    customer: AuthCustomer;
+    /** Access token for authenticated requests. Null if email confirmation is required. */
+    access_token: string | null;
+    /** Refresh token for renewing the session. Null if email confirmation is required. */
+    refresh_token: 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. */
+interface LoginParams {
+    /** Customer email address. */
+    email: string;
+    /** Customer password. */
+    password: string;
+}
+/** Response from a successful login. */
+interface LoginResult {
+    customer: AuthCustomer;
+    /** Access token for authenticated requests. */
+    access_token: string | null;
+    /** Refresh token for renewing the session. */
+    refresh_token: string | null;
+}
+/** Stored session with tokens and customer identity. */
+interface AuthSession {
+    customer: AuthCustomer;
+    accessToken: string;
+    refreshToken: string;
+}
+
+/**
+ * Customer authentication client for the cStar widget API.
+ *
+ * Provides signup, login, and session management for end-customers
+ * interacting with your support widget or custom integration.
+ *
+ * ```typescript
+ * import { AuthClient } from '@cstar.help/js/auth';
+ *
+ * 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',
+ * });
+ *
+ * // Log in an existing customer
+ * const session = await auth.login({
+ *   email: 'jane@example.com',
+ *   password: 'securepass123',
+ * });
+ *
+ * // Check current session
+ * const current = auth.getSession();
+ * ```
+ */
+declare class AuthClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private session;
+    constructor(config: AuthConfig);
+    /**
+     * Create a new customer account.
+     *
+     * If the team requires email confirmation, returns a `SignupConfirmationResult`
+     * instead of tokens. Check for `requiresConfirmation` in the response.
+     *
+     * @throws Error on validation failure, duplicate email, or server error
+     */
+    signup(params: SignupParams): Promise<SignupResult | SignupConfirmationResult>;
+    /**
+     * Log in an existing customer with email and password.
+     *
+     * 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. */
+    logout(): void;
+    /** Get the current session, or null if not authenticated. */
+    getSession(): AuthSession | null;
+    /** Get the authenticated customer, or null if not logged in. */
+    getCustomer(): AuthCustomer | null;
+    /** Whether a customer is currently authenticated. */
+    get isAuthenticated(): boolean;
+    /** Get the current access token, or null. Useful for passing to ChatClient. */
+    get accessToken(): string | null;
+    private fetch;
+}
+
+export { AuthClient, type AuthConfig, type AuthCustomer, type AuthSession, type LoginParams, type LoginResult, type SignupConfirmationResult, type SignupParams, type SignupResult };

package/dist/auth/index.js

@@ -0,0 +1,102 @@
+// src/auth/index.ts
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var AuthClient = class {
+  constructor(config) {
+    this.session = null;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+  }
+  /**
+   * Create a new customer account.
+   *
+   * If the team requires email confirmation, returns a `SignupConfirmationResult`
+   * instead of tokens. Check for `requiresConfirmation` in the response.
+   *
+   * @throws Error on validation failure, duplicate email, or server error
+   */
+  async signup(params) {
+    const response = await this.fetch(
+      "/widget/api/auth/signup",
+      {
+        method: "POST",
+        body: {
+          team_id: this.teamSlug,
+          email: params.email,
+          password: params.password,
+          name: params.name
+        }
+      }
+    );
+    if ("access_token" in response && response.access_token && response.customer) {
+      this.session = {
+        customer: response.customer,
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token
+      };
+    }
+    return response;
+  }
+  /**
+   * Log in an existing customer with email and password.
+   *
+   * 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
+   */
+  async login(params) {
+    const response = await this.fetch("/widget/api/auth/login", {
+      method: "POST",
+      body: {
+        team_id: this.teamSlug,
+        email: params.email,
+        password: params.password
+      }
+    });
+    if (response.access_token && response.customer) {
+      this.session = {
+        customer: response.customer,
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token
+      };
+    }
+    return response;
+  }
+  /** Clear the stored session. */
+  logout() {
+    this.session = null;
+  }
+  /** Get the current session, or null if not authenticated. */
+  getSession() {
+    return this.session;
+  }
+  /** Get the authenticated customer, or null if not logged in. */
+  getCustomer() {
+    return this.session?.customer ?? null;
+  }
+  /** Whether a customer is currently authenticated. */
+  get isAuthenticated() {
+    return this.session !== null;
+  }
+  /** Get the current access token, or null. Useful for passing to ChatClient. */
+  get accessToken() {
+    return this.session?.accessToken ?? null;
+  }
+  async fetch(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await globalThis.fetch(url, {
+      method: options.method,
+      headers: { "Content-Type": "application/json" },
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: "Request failed" }));
+      const message = errorBody.error ?? errorBody.message ?? `Auth API error: ${response.status}`;
+      throw new Error(message);
+    }
+    return response.json();
+  }
+};
+export {
+  AuthClient
+};