@cstar.help/js 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -499,8 +499,401 @@ declare class ArticlesResource extends BaseResource<Article, ArticleListParams,
     constructor(client: HttpClient);
 }
 
-/** All webhook event types supported by cStar. */
-type WebhookEventType = 'ticket.created' | 'ticket.updated' | 'ticket.closed' | 'ticket.message_added' | 'customer.created' | 'customer.updated' | 'article.created' | 'article.published' | 'article.updated' | 'boss.spawned' | 'boss.defeated' | 'player.level_up' | 'achievement.unlocked' | 'survey.submitted';
+/** Every webhook event type cStar can dispatch. */
+type WebhookEventType = 'article.created' | 'article.deleted' | 'article.published' | 'article.updated' | 'boss.damaged' | 'boss.defeated' | 'boss.spawned' | 'community_post.commented' | 'community_post.created' | 'community_post.deleted' | 'community_post.status_changed' | 'community_post.updated' | 'community_post.voted' | 'customer.created' | 'customer.deleted' | 'customer.updated' | 'customer_group.created' | 'customer_group.deleted' | 'customer_group.updated' | 'player.achievement_unlocked' | 'player.level_up' | 'player.quest_completed' | 'player.streak_milestone' | 'player.xp_gained' | 'social.high_five_sent' | 'social.one_up_sent' | 'survey.submitted' | 'ticket.assigned' | 'ticket.closed' | 'ticket.created' | 'ticket.deleted' | 'ticket.message_added' | 'ticket.updated';
+/** Payload for `article.created` events. */
+interface ArticleCreatedPayload {
+    article: {
+        id: string;
+        title: string;
+        slug: string;
+        is_public: boolean;
+        created_at: string;
+    };
+}
+/** Payload for `article.deleted` events. */
+interface ArticleDeletedPayload {
+    id: string;
+}
+/** Payload for `article.published` events. */
+interface ArticlePublishedPayload {
+    article: {
+        id: string;
+        title: string;
+        slug: string;
+        is_public: boolean;
+        published_at: string;
+    };
+}
+/** Payload for `article.updated` events. */
+interface ArticleUpdatedPayload {
+    article: {
+        id: string;
+        title: string;
+        slug: string;
+        is_public: boolean;
+    };
+}
+/** Payload for `boss.damaged` events. */
+interface BossDamagedPayload {
+    boss: {
+        id: string;
+        current_hp: number;
+    };
+    damage: number;
+    by: {
+        agent_id: string;
+        name: string;
+    };
+}
+/** Payload for `boss.defeated` events. */
+interface BossDefeatedPayload {
+    boss: {
+        id: string;
+        name: string;
+    };
+    final_blow_by: {
+        agent_id: string;
+        name: string;
+    };
+    team_xp_awarded: number;
+}
+/** Payload for `boss.spawned` events. */
+interface BossSpawnedPayload {
+    boss: {
+        id: string;
+        name: string;
+        level: number;
+        max_hp: number;
+    };
+}
+/** Payload for `community_post.commented` events. */
+interface CommunityPostCommentedPayload {
+    comment: {
+        id: string;
+        post_id: string;
+        content: string;
+        author_id: string;
+        created_at: string;
+    };
+}
+/** Payload for `community_post.created` events. */
+interface CommunityPostCreatedPayload {
+    post: {
+        id: string;
+        prefixed_id: string;
+        title: string;
+        status: string;
+        visibility: string;
+        topic: string;
+        created_at: string;
+    };
+}
+/** Payload for `community_post.deleted` events. */
+interface CommunityPostDeletedPayload {
+    post: {
+        id: string;
+        prefixed_id?: string;
+        title?: string;
+    };
+}
+/** Payload for `community_post.status_changed` events. */
+interface CommunityPostStatusChangedPayload {
+    post: {
+        id: string;
+        title: string;
+        status: string;
+        visibility: string;
+    };
+}
+/** Payload for `community_post.updated` events. */
+interface CommunityPostUpdatedPayload {
+    post: {
+        id: string;
+        title: string;
+        status: string;
+        visibility: string;
+    };
+}
+/** Payload for `community_post.voted` events. */
+interface CommunityPostVotedPayload {
+    post: {
+        id: string;
+        vote_count: number;
+    };
+    voter: {
+        id: string;
+    };
+    direction: string;
+}
+/** Payload for `customer.created` events. */
+interface CustomerCreatedPayload {
+    customer: {
+        id: string;
+        name: string;
+        email: string;
+        status: string;
+        tags: Array<string>;
+        created_at: string;
+    };
+}
+/** Payload for `customer.deleted` events. */
+interface CustomerDeletedPayload {
+    id: string;
+}
+/** Payload for `customer.updated` events. */
+interface CustomerUpdatedPayload {
+    customer: {
+        id: string;
+        name: string;
+        email: string;
+        status: string;
+        tags: Array<string>;
+    };
+    changes: {
+        tags: {
+            from: Array<string>;
+            to: Array<string>;
+        };
+    };
+}
+/** Payload for `customer_group.created` events. */
+interface CustomerGroupCreatedPayload {
+    group: {
+        id: string;
+        name: string;
+        color: string;
+        member_count: number;
+    };
+}
+/** Payload for `customer_group.deleted` events. */
+interface CustomerGroupDeletedPayload {
+    customer_group: {
+        id: string;
+    };
+}
+/** Payload for `customer_group.updated` events. */
+interface CustomerGroupUpdatedPayload {
+    group: {
+        id: string;
+        name: string;
+        color: string;
+        member_count: number;
+    };
+}
+/** Payload for `player.achievement_unlocked` events. */
+interface PlayerAchievementUnlockedPayload {
+    player: {
+        agent_id: string;
+        name: string;
+    };
+    achievement: {
+        id: string;
+        name: string;
+        xp: number;
+    };
+}
+/** Payload for `player.level_up` events. */
+interface PlayerLevelUpPayload {
+    player: {
+        agent_id: string;
+        name: string;
+    };
+    level: {
+        from: number;
+        to: number;
+    };
+    title_unlocked: string;
+}
+/** Payload for `player.quest_completed` events. */
+interface PlayerQuestCompletedPayload {
+    player: {
+        agent_id: string;
+        name: string;
+    };
+    quest: {
+        id: string;
+        name: string;
+        xp: number;
+    };
+}
+/** Payload for `player.streak_milestone` events. */
+interface PlayerStreakMilestonePayload {
+    player: {
+        agent_id: string;
+        name: string;
+    };
+    streak_days: number;
+    milestone: number;
+}
+/** Payload for `player.xp_gained` events. */
+interface PlayerXpGainedPayload {
+    player: {
+        agent_id: string;
+        name: string;
+    };
+    amount: number;
+    reason: string;
+    ticket_id: string;
+}
+/** Payload for `social.high_five_sent` events. */
+interface SocialHighFiveSentPayload {
+    from_team: {
+        id: string;
+        name: string;
+    };
+    to_team: {
+        id: string;
+        name: string;
+    };
+    message: string;
+}
+/** Payload for `social.one_up_sent` events. */
+interface SocialOneUpSentPayload {
+    from: {
+        agent_id: string;
+        name: string;
+    };
+    to: {
+        agent_id: string;
+        name: string;
+    };
+    ticket_id: string;
+    message: string;
+}
+/** Payload for `survey.submitted` events. */
+interface SurveySubmittedPayload {
+    survey: {
+        id: string;
+        ticket_id: string;
+        score: number;
+        comment: string;
+        submitted_at: string;
+    };
+    customer: {
+        id: string;
+        email: string;
+    };
+}
+/** Payload for `ticket.assigned` events. */
+interface TicketAssignedPayload {
+    ticket: {
+        id: string;
+        prefixed_id: string;
+    };
+    assignee: {
+        id: string;
+        name: string;
+        email: string;
+    };
+    previous_assignee: null;
+}
+/** Payload for `ticket.closed` events. */
+interface TicketClosedPayload {
+    ticket: {
+        id: string;
+        prefixed_id: string;
+        title: string;
+        status: string;
+        priority: string;
+        channel: string;
+        resolved_at: string;
+    };
+}
+/** Payload for `ticket.created` events. */
+interface TicketCreatedPayload {
+    ticket: {
+        id: string;
+        prefixed_id: string;
+        title: string;
+        status: string;
+        priority: string;
+        channel: string;
+        customer_id: string;
+        created_at: string;
+    };
+    customer: {
+        id: string;
+        name: string;
+        email: string;
+    };
+}
+/** Payload for `ticket.deleted` events. */
+interface TicketDeletedPayload {
+    id: string;
+}
+/** Payload for `ticket.message_added` events. */
+interface TicketMessageAddedPayload {
+    ticket: {
+        id: string;
+        dashboard_url: string | null;
+    };
+    message: {
+        id: string;
+        sender: string;
+        sender_name: string | null;
+        content: string;
+        created_at: string;
+    };
+    customer?: {
+        id: string;
+        name: string | null;
+        email: string | null;
+    };
+}
+/** Payload for `ticket.updated` events. */
+interface TicketUpdatedPayload {
+    ticket: {
+        id: string;
+        prefixed_id: string;
+        title: string;
+        status: string;
+        priority: string;
+        channel: string;
+    };
+    changes: {
+        priority: {
+            from: string;
+            to: string;
+        };
+    };
+}
+/** Maps each event type to its payload interface — used internally for the discriminated union. */
+interface WebhookEventDataMap {
+    'article.created': ArticleCreatedPayload;
+    'article.deleted': ArticleDeletedPayload;
+    'article.published': ArticlePublishedPayload;
+    'article.updated': ArticleUpdatedPayload;
+    'boss.damaged': BossDamagedPayload;
+    'boss.defeated': BossDefeatedPayload;
+    'boss.spawned': BossSpawnedPayload;
+    'community_post.commented': CommunityPostCommentedPayload;
+    'community_post.created': CommunityPostCreatedPayload;
+    'community_post.deleted': CommunityPostDeletedPayload;
+    'community_post.status_changed': CommunityPostStatusChangedPayload;
+    'community_post.updated': CommunityPostUpdatedPayload;
+    'community_post.voted': CommunityPostVotedPayload;
+    'customer.created': CustomerCreatedPayload;
+    'customer.deleted': CustomerDeletedPayload;
+    'customer.updated': CustomerUpdatedPayload;
+    'customer_group.created': CustomerGroupCreatedPayload;
+    'customer_group.deleted': CustomerGroupDeletedPayload;
+    'customer_group.updated': CustomerGroupUpdatedPayload;
+    'player.achievement_unlocked': PlayerAchievementUnlockedPayload;
+    'player.level_up': PlayerLevelUpPayload;
+    'player.quest_completed': PlayerQuestCompletedPayload;
+    'player.streak_milestone': PlayerStreakMilestonePayload;
+    'player.xp_gained': PlayerXpGainedPayload;
+    'social.high_five_sent': SocialHighFiveSentPayload;
+    'social.one_up_sent': SocialOneUpSentPayload;
+    'survey.submitted': SurveySubmittedPayload;
+    'ticket.assigned': TicketAssignedPayload;
+    'ticket.closed': TicketClosedPayload;
+    'ticket.created': TicketCreatedPayload;
+    'ticket.deleted': TicketDeletedPayload;
+    'ticket.message_added': TicketMessageAddedPayload;
+    'ticket.updated': TicketUpdatedPayload;
+}
 /** A webhook event delivered to your endpoint. */
 interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
     /** Unique event ID (idempotency key). */
@@ -512,19 +905,10 @@ interface WebhookEvent<T extends WebhookEventType = WebhookEventType> {
     /** Team that owns this event. */
     team_id: string;
     /** Event-specific payload. */
-    data: WebhookEventData<T>;
-}
-/** Discriminated union mapping event types to their data payloads. */
-type WebhookEventData<T extends WebhookEventType> = T extends 'ticket.created' | 'ticket.updated' | 'ticket.closed' ? {
-    ticket: Ticket;
-} : T extends 'ticket.message_added' ? {
-    ticket: Ticket;
-    message: Message;
-} : T extends 'customer.created' | 'customer.updated' ? {
-    customer: Customer;
-} : T extends 'article.created' | 'article.published' | 'article.updated' ? {
-    article: Article;
-} : Record<string, unknown>;
+    data: WebhookEventDataMap[T];
+}
+
+type WebhookEventData<T extends WebhookEventType> = WebhookEventDataMap[T];
 
 /** A cStar webhook endpoint. */
 interface Webhook {

package/dist/quickhelp/index.cjs

@@ -0,0 +1,102 @@
+"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/quickhelp/index.ts
+var quickhelp_exports = {};
+__export(quickhelp_exports, {
+  QuickHelpClient: () => QuickHelpClient,
+  QuickHelpError: () => QuickHelpError
+});
+module.exports = __toCommonJS(quickhelp_exports);
+var DEFAULT_BASE_URL = "https://www.cstar.help";
+var QuickHelpClient = class {
+  constructor(config) {
+    if (!config?.teamId) {
+      throw new Error("QuickHelpClient: teamId is required");
+    }
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamId = config.teamId;
+  }
+  /**
+   * Fetch the sanitized public config (title, subtitle, placeholder,
+   * theme overrides). Never includes agent id or escalation contact
+   * info — those leak only through the agent's own replies.
+   *
+   * Returns `null` if Quick Help is disabled on the team (404).
+   */
+  async config() {
+    const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(this.teamId)}`;
+    const res = await globalThis.fetch(url, { method: "GET" });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      const body2 = await res.json().catch(() => null);
+      throw new Error(body2?.error?.message ?? `Quick Help config failed: ${res.status}`);
+    }
+    const body = await res.json();
+    return body.data;
+  }
+  /**
+   * Ask a question and get an answer. On first turn, omit `sessionId`;
+   * the server mints one and you MUST pass it back on follow-ups. On
+   * rate-limit (429) the returned Error has a `retryAfterSeconds`
+   * property set from the response body.
+   */
+  async ask(params) {
+    const url = `${this.baseUrl}/api/quickhelp/ask`;
+    const res = await globalThis.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        team_id: this.teamId,
+        session_id: params.sessionId ?? null,
+        question: params.question
+      })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || !body?.success || !body.data) {
+      const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;
+      const err = new QuickHelpError(message, {
+        status: res.status,
+        code: body?.error?.code,
+        retryAfterSeconds: parseRetryAfter(res.headers.get("retry-after"))
+      });
+      throw err;
+    }
+    return body.data;
+  }
+};
+var QuickHelpError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = "QuickHelpError";
+    this.status = opts.status;
+    this.code = opts.code;
+    this.retryAfterSeconds = opts.retryAfterSeconds;
+  }
+};
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const n = Number(header);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  QuickHelpClient,
+  QuickHelpError
+});

package/dist/quickhelp/index.d.cts

@@ -0,0 +1,97 @@
+/** Options for the QuickHelpClient. No auth — Quick Help is anonymous by design. */
+interface QuickHelpConfig {
+    /** Your team's UUID. Required. */
+    teamId: string;
+    /** Override the base URL (defaults to https://www.cstar.help). */
+    baseUrl?: string;
+}
+/** Sanitized config the server returns to anonymous visitors. */
+interface QuickHelpPublicConfig {
+    headerTitle: string;
+    headerSubtitle: string;
+    placeholderText: string;
+    theme: 'light' | 'dark' | null;
+    primaryColor: string | null;
+    fontHeading: string | null;
+    fontBody: string | null;
+    borderRadius: string | null;
+}
+type QuickHelpTurnOutcome = 'answered' | 'escalated' | 'needs_clarification';
+interface QuickHelpAskParams {
+    /** The visitor's question. Max 2000 chars. */
+    question: string;
+    /**
+     * The session id from a previous `ask()` call, if this is a follow-up
+     * turn. Omit or pass null on the first turn; the server mints a new
+     * id and returns it in `sessionId`.
+     */
+    sessionId?: string | null;
+}
+interface QuickHelpAskResult {
+    sessionId: string;
+    answer: string;
+    turnOutcome: QuickHelpTurnOutcome;
+    turnNumber: number;
+}
+
+/**
+ * Quick Help — anonymous AI Q&A client.
+ *
+ * No API key. No login. The Quick Help widget is the exact same product
+ * cStar's marketing site dogfoods on its homepage, just driven
+ * programmatically. Sessions live entirely in memory on the caller side;
+ * the server hands back a `sessionId` on the first turn and expects you
+ * to pass it back on follow-ups so the orchestrator can see prior
+ * transcript.
+ *
+ * ```typescript
+ * import { QuickHelpClient } from '@cstar.help/js/quickhelp';
+ *
+ * const qh = new QuickHelpClient({ teamId: 'your-team-uuid' });
+ *
+ * const turn1 = await qh.ask({ question: 'How do I reset my password?' });
+ * console.log(turn1.answer);
+ *
+ * const turn2 = await qh.ask({
+ *   question: 'Can you walk me through that?',
+ *   sessionId: turn1.sessionId
+ * });
+ * ```
+ */
+declare class QuickHelpClient {
+    private readonly baseUrl;
+    private readonly teamId;
+    constructor(config: QuickHelpConfig);
+    /**
+     * Fetch the sanitized public config (title, subtitle, placeholder,
+     * theme overrides). Never includes agent id or escalation contact
+     * info — those leak only through the agent's own replies.
+     *
+     * Returns `null` if Quick Help is disabled on the team (404).
+     */
+    config(): Promise<QuickHelpPublicConfig | null>;
+    /**
+     * Ask a question and get an answer. On first turn, omit `sessionId`;
+     * the server mints one and you MUST pass it back on follow-ups. On
+     * rate-limit (429) the returned Error has a `retryAfterSeconds`
+     * property set from the response body.
+     */
+    ask(params: QuickHelpAskParams): Promise<QuickHelpAskResult>;
+}
+/**
+ * Thrown by `QuickHelpClient.ask` when the request fails. Carries the
+ * HTTP status + error code + Retry-After (on 429) so callers can back
+ * off intelligently.
+ */
+declare class QuickHelpError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string;
+        retryAfterSeconds?: number;
+    });
+}
+
+export { type QuickHelpAskParams, type QuickHelpAskResult, QuickHelpClient, type QuickHelpConfig, QuickHelpError, type QuickHelpPublicConfig, type QuickHelpTurnOutcome };