@cstar.help/js 0.12.1 → 0.13.0

package/dist/quickhelp/index.js

@@ -1,3 +1,155 @@
+// src/errors.ts
+var ErrorType = {
+  AUTHENTICATION_ERROR: "authentication_error",
+  PERMISSION_ERROR: "permission_error",
+  INVALID_REQUEST_ERROR: "invalid_request_error",
+  NOT_FOUND_ERROR: "not_found_error",
+  CONFLICT_ERROR: "conflict_error",
+  RATE_LIMIT_ERROR: "rate_limit_error",
+  FEATURE_NOT_CONFIGURED: "feature_not_configured",
+  API_ERROR: "api_error",
+  SERVER_ERROR: "server_error"
+};
+var DEFAULT_DOC_URL = "https://cstar.help/developers/api/errors";
+function normalizeArgs(messageOrStatus, maybeBody, defaults) {
+  if (typeof messageOrStatus === "string") {
+    return {
+      statusCode: defaults?.code === "rate_limit_error" ? 429 : 0,
+      body: {
+        type: defaults?.type ?? ErrorType.API_ERROR,
+        code: defaults?.code ?? "sdk_error",
+        message: messageOrStatus,
+        doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL,
+        ...defaults?.feature ? { feature: defaults.feature } : {},
+        ...defaults?.enable_url ? { enable_url: defaults.enable_url } : {}
+      }
+    };
+  }
+  return {
+    statusCode: messageOrStatus,
+    body: maybeBody ?? {
+      type: defaults?.type ?? ErrorType.API_ERROR,
+      code: defaults?.code ?? "unknown_error",
+      message: defaults?.message ?? `Request failed with status ${messageOrStatus}`,
+      doc_url: defaults?.doc_url ?? DEFAULT_DOC_URL
+    }
+  };
+}
+var CStarError = class extends Error {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body);
+    super(resolved.message);
+    this.name = "CStarError";
+    this.type = resolved.type;
+    this.code = resolved.code;
+    this.param = resolved.param;
+    this.docUrl = resolved.doc_url;
+    this.requestId = resolved.request_id;
+    this.statusCode = statusCode;
+  }
+};
+var CStarAuthenticationError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.AUTHENTICATION_ERROR,
+      code: "authentication_failed",
+      doc_url: `${DEFAULT_DOC_URL}#authentication-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarAuthenticationError";
+  }
+};
+var CStarRateLimitError = class extends CStarError {
+  constructor(messageOrStatus, body, retryAfter) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.RATE_LIMIT_ERROR,
+      code: "rate_limit_exceeded",
+      doc_url: `${DEFAULT_DOC_URL}#rate-limit-error`
+    });
+    super(statusCode === 0 ? 429 : statusCode, resolved);
+    this.name = "CStarRateLimitError";
+    this.retryAfter = retryAfter ?? 60;
+  }
+};
+var CStarNotFoundError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.NOT_FOUND_ERROR,
+      code: "resource_not_found",
+      doc_url: `${DEFAULT_DOC_URL}#not-found-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarNotFoundError";
+  }
+};
+var CStarValidationError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.INVALID_REQUEST_ERROR,
+      code: "validation_error",
+      doc_url: `${DEFAULT_DOC_URL}#validation-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarValidationError";
+  }
+};
+var CStarPermissionError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.PERMISSION_ERROR,
+      code: "permission_denied",
+      doc_url: `${DEFAULT_DOC_URL}#permission-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarPermissionError";
+  }
+};
+var CStarConflictError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.CONFLICT_ERROR,
+      code: "conflict",
+      doc_url: `${DEFAULT_DOC_URL}#conflict-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarConflictError";
+  }
+};
+var CStarServerError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.SERVER_ERROR,
+      code: "server_error",
+      doc_url: `${DEFAULT_DOC_URL}#server-error`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarServerError";
+  }
+};
+var CStarFeatureDisabledError = class extends CStarError {
+  constructor(messageOrStatus, body) {
+    const { statusCode, body: resolved } = normalizeArgs(messageOrStatus, body, {
+      type: ErrorType.FEATURE_NOT_CONFIGURED,
+      code: "feature_not_configured",
+      doc_url: `${DEFAULT_DOC_URL}#feature-not-configured`
+    });
+    super(statusCode, resolved);
+    this.name = "CStarFeatureDisabledError";
+    this.feature = resolved.feature ?? "unknown";
+    this.enableUrl = resolved.enable_url ?? "";
+  }
+};
+var TYPE_TO_CLASS = {
+  [ErrorType.AUTHENTICATION_ERROR]: CStarAuthenticationError,
+  [ErrorType.PERMISSION_ERROR]: CStarPermissionError,
+  [ErrorType.RATE_LIMIT_ERROR]: CStarRateLimitError,
+  [ErrorType.NOT_FOUND_ERROR]: CStarNotFoundError,
+  [ErrorType.INVALID_REQUEST_ERROR]: CStarValidationError,
+  [ErrorType.CONFLICT_ERROR]: CStarConflictError,
+  [ErrorType.SERVER_ERROR]: CStarServerError,
+  [ErrorType.FEATURE_NOT_CONFIGURED]: CStarFeatureDisabledError
+};
+
 // src/quickhelp/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var QuickHelpClient = class {
@@ -7,6 +159,16 @@ var QuickHelpClient = class {
     }
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.teamId = config.teamId;
+    this.publishableKey = config.publishableKey ?? null;
+    this.mode = this.publishableKey?.startsWith("pk_test_") ? "test" : "live";
+    if (this.publishableKey && !/^pk_(test|live)_/.test(this.publishableKey)) {
+      throw new Error(
+        "[cStar] QuickHelpClient: publishableKey must start with `pk_test_` or `pk_live_`. Secret keys (`sk_*`) cannot be used in browser/anonymous contexts."
+      );
+    }
+  }
+  authHeaders() {
+    return this.publishableKey ? { Authorization: `Bearer ${this.publishableKey}` } : {};
   }
   /**
    * Fetch the sanitized public config (title, subtitle, placeholder,
@@ -17,7 +179,7 @@ var QuickHelpClient = class {
    */
   async config() {
     const url = `${this.baseUrl}/api/quickhelp/config/${encodeURIComponent(this.teamId)}`;
-    const res = await globalThis.fetch(url, { method: "GET" });
+    const res = await globalThis.fetch(url, { method: "GET", headers: this.authHeaders() });
     if (res.status === 404) return null;
     if (!res.ok) {
       const body2 = await res.json().catch(() => null);
@@ -36,7 +198,7 @@ var QuickHelpClient = class {
     const url = `${this.baseUrl}/api/quickhelp/ask`;
     const res = await globalThis.fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...this.authHeaders() },
       body: JSON.stringify({
         team_id: this.teamId,
         session_id: params.sessionId ?? null,
@@ -45,6 +207,16 @@ var QuickHelpClient = class {
     });
     const body = await res.json().catch(() => null);
     if (!res.ok || !body?.success || !body.data) {
+      if (res.status === 503 || body?.error?.code === "feature_not_configured") {
+        throw new CStarFeatureDisabledError(res.status, {
+          type: "feature_not_configured",
+          code: "feature_not_configured",
+          message: body?.error?.message ?? "Quick Help is not available on this team. Enable an AI Agent (Settings \u2192 AI Agents) and configure Quick Help (Settings \u2192 Quick Help) before calling .ask().",
+          doc_url: "https://cstar.help/developers/api/errors#feature-not-configured",
+          feature: "quickHelp",
+          enable_url: `${this.baseUrl}/team/${encodeURIComponent(this.teamId)}/settings?section=quickHelp`
+        });
+      }
       const message = body?.error?.message ?? `Quick Help ask failed: ${res.status}`;
       const err = new QuickHelpError(message, {
         status: res.status,

package/dist/webhook/index.cjs

@@ -21,9 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var webhook_exports = {};
 __export(webhook_exports, {
   WebhookSignatureVerificationError: () => WebhookSignatureVerificationError,
-  constructEvent: () => constructEvent,
   constructEventAsync: () => constructEventAsync,
-  verifySignature: () => verifySignature,
   verifySignatureAsync: () => verifySignatureAsync
 });
 module.exports = __toCommonJS(webhook_exports);
@@ -33,14 +31,6 @@ var WebhookSignatureVerificationError = class extends Error {
     this.name = "WebhookSignatureVerificationError";
   }
 };
-function constructEvent(rawBody, signature, secret) {
-  if (!verifySignature(rawBody, signature, secret)) {
-    throw new WebhookSignatureVerificationError(
-      "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint secret."
-    );
-  }
-  return JSON.parse(rawBody);
-}
 async function constructEventAsync(rawBody, signature, secret) {
   const valid = await verifySignatureAsync(rawBody, signature, secret);
   if (!valid) {
@@ -50,12 +40,6 @@ async function constructEventAsync(rawBody, signature, secret) {
   }
   return JSON.parse(rawBody);
 }
-function verifySignature(rawBody, signature, secret) {
-  const crypto2 = require("crypto");
-  const expected = "sha256=" + crypto2.createHmac("sha256", secret).update(rawBody).digest("hex");
-  if (signature.length !== expected.length) return false;
-  return crypto2.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
-}
 async function verifySignatureAsync(rawBody, signature, secret) {
   const encoder = new TextEncoder();
   const key = await crypto.subtle.importKey(
@@ -77,8 +61,6 @@ async function verifySignatureAsync(rawBody, signature, secret) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   WebhookSignatureVerificationError,
-  constructEvent,
   constructEventAsync,
-  verifySignature,
   verifySignatureAsync
 });

package/dist/webhook/index.d.cts

@@ -0,0 +1,440 @@
+/** 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;
+    };
+    changes?: Record<string, {
+        from: string;
+        to: 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?: Record<string, {
+        from: string;
+        to: string;
+    } | {
+        from: Array<string>;
+        to: Array<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). */
+    id: string;
+    /** Event type. */
+    type: T;
+    /** When the event was created (ISO 8601). */
+    created_at: string;
+    /** Team that owns this event. */
+    team_id: string;
+    /** Event-specific payload. */
+    data: WebhookEventDataMap[T];
+}
+
+/** Thrown when webhook signature verification fails. */
+declare class WebhookSignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a webhook signature and parse the event.
+ *
+ * Uses the Web Crypto API — works in browsers, Cloudflare Workers, Vercel Edge,
+ * Deno, Bun, and Node.js 18+. This is the recommended API for all runtimes.
+ *
+ * For a synchronous Node-only variant, import from `@cstar.help/js/webhook/node`.
+ *
+ * @param rawBody - Raw request body as a string (NOT parsed JSON)
+ * @param signature - Value of the `X-Signature` header
+ * @param secret - Your webhook endpoint's secret (`whsec_*`)
+ * @returns Parsed and verified webhook event
+ * @throws {WebhookSignatureVerificationError} If verification fails
+ */
+declare function constructEventAsync(rawBody: string, signature: string, secret: string): Promise<WebhookEvent>;
+/**
+ * Verify an HMAC-SHA256 signature using the Web Crypto API.
+ * Constant-time comparison to prevent timing attacks.
+ */
+declare function verifySignatureAsync(rawBody: string, signature: string, secret: string): Promise<boolean>;
+
+export { type WebhookEvent, WebhookSignatureVerificationError, constructEventAsync, verifySignatureAsync };