@cstar.help/js 0.1.0

package/dist/webhook/index.cjs

@@ -0,0 +1,84 @@
+"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/webhook/index.ts
+var webhook_exports = {};
+__export(webhook_exports, {
+  WebhookSignatureVerificationError: () => WebhookSignatureVerificationError,
+  constructEvent: () => constructEvent,
+  constructEventAsync: () => constructEventAsync,
+  verifySignature: () => verifySignature,
+  verifySignatureAsync: () => verifySignatureAsync
+});
+module.exports = __toCommonJS(webhook_exports);
+var WebhookSignatureVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    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) {
+    throw new WebhookSignatureVerificationError(
+      "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint 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(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(rawBody));
+  const expected = "sha256=" + Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (signature.length !== expected.length) return false;
+  let result = 0;
+  for (let i = 0; i < signature.length; i++) {
+    result |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return result === 0;
+}
+// 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,163 @@
+/** Metadata: string key-value pairs. Max 50 keys, 40-char keys, 500-char values. */
+type Metadata = Record<string, string>;
+
+/** A message on a ticket. */
+interface Message {
+    id: string;
+    object: 'message';
+    sender: 'customer' | 'agent' | 'system';
+    content: string;
+    senderId: string | null;
+    senderName: string | null;
+    senderAvatarUrl: string | null;
+    createdAt: string;
+    mergedFromShortId: string | null;
+}
+
+/** A cStar support ticket. */
+interface Ticket {
+    id: string;
+    object: 'ticket';
+    title: string;
+    priority: 'low' | 'normal' | 'high' | 'urgent';
+    status: string;
+    customerId: string | null;
+    customerName: string | null;
+    assignedTo: string | null;
+    tags: string[];
+    notes: string | null;
+    messageCount: number;
+    responseDeadline: string | null;
+    resolutionDeadline: string | null;
+    firstResponseAt: string | null;
+    responseTier: string | null;
+    resolutionTier: string | null;
+    slaPaused: boolean;
+    metadata: Metadata;
+    createdAt: string;
+    closedAt: string | null;
+    updatedAt: string;
+    /** Present when expand includes 'messages' or on single-ticket GET. */
+    messages?: Message[];
+    /** Present when expand includes 'customer'. */
+    customer?: TicketCustomerSummary | null;
+}
+/** Inline customer summary when expanding on a ticket. */
+interface TicketCustomerSummary {
+    id: string;
+    object: 'customer';
+    name: string;
+    email: string;
+    sentiment: string;
+    status: string;
+}
+
+/** A cStar customer. */
+interface Customer {
+    id: string;
+    object: 'customer';
+    name: string;
+    email: string;
+    sentiment: string;
+    status: string;
+    tags: string[];
+    notes: string | null;
+    customFields: Record<string, unknown>;
+    ticketCount: number;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** A cStar knowledge base article. */
+interface Article {
+    id: string;
+    object: 'article';
+    title: string;
+    slug: string | null;
+    excerpt: string | null;
+    content: string | null;
+    category: string;
+    status: 'draft' | 'published';
+    tags: string[];
+    notes: string | null;
+    viewCount: number;
+    useCount: number;
+    readTime: string;
+    isPublic: boolean;
+    publishedAt: string | null;
+    metaDescription: string | null;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** 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';
+/** 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: 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>;
+
+/** Thrown when webhook signature verification fails. */
+declare class WebhookSignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a webhook signature and parse the event (synchronous, Node.js only).
+ *
+ * Uses Node.js `crypto` module for timing-safe HMAC comparison.
+ * For browser/edge environments, use `constructEventAsync()`.
+ *
+ * @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 constructEvent(rawBody: string, signature: string, secret: string): WebhookEvent;
+/**
+ * Verify a webhook signature and parse the event (async, works everywhere).
+ *
+ * Uses the Web Crypto API — compatible with browsers, Deno, Cloudflare Workers,
+ * and Node.js 18+.
+ *
+ * @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 (synchronous, Node.js only).
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+declare function verifySignature(rawBody: string, signature: string, secret: string): boolean;
+/**
+ * Verify an HMAC-SHA256 signature (async, works everywhere).
+ * Uses the Web Crypto API with constant-time comparison.
+ */
+declare function verifySignatureAsync(rawBody: string, signature: string, secret: string): Promise<boolean>;
+
+export { type WebhookEvent, WebhookSignatureVerificationError, constructEvent, constructEventAsync, verifySignature, verifySignatureAsync };

package/dist/webhook/index.d.ts

@@ -0,0 +1,163 @@
+/** Metadata: string key-value pairs. Max 50 keys, 40-char keys, 500-char values. */
+type Metadata = Record<string, string>;
+
+/** A message on a ticket. */
+interface Message {
+    id: string;
+    object: 'message';
+    sender: 'customer' | 'agent' | 'system';
+    content: string;
+    senderId: string | null;
+    senderName: string | null;
+    senderAvatarUrl: string | null;
+    createdAt: string;
+    mergedFromShortId: string | null;
+}
+
+/** A cStar support ticket. */
+interface Ticket {
+    id: string;
+    object: 'ticket';
+    title: string;
+    priority: 'low' | 'normal' | 'high' | 'urgent';
+    status: string;
+    customerId: string | null;
+    customerName: string | null;
+    assignedTo: string | null;
+    tags: string[];
+    notes: string | null;
+    messageCount: number;
+    responseDeadline: string | null;
+    resolutionDeadline: string | null;
+    firstResponseAt: string | null;
+    responseTier: string | null;
+    resolutionTier: string | null;
+    slaPaused: boolean;
+    metadata: Metadata;
+    createdAt: string;
+    closedAt: string | null;
+    updatedAt: string;
+    /** Present when expand includes 'messages' or on single-ticket GET. */
+    messages?: Message[];
+    /** Present when expand includes 'customer'. */
+    customer?: TicketCustomerSummary | null;
+}
+/** Inline customer summary when expanding on a ticket. */
+interface TicketCustomerSummary {
+    id: string;
+    object: 'customer';
+    name: string;
+    email: string;
+    sentiment: string;
+    status: string;
+}
+
+/** A cStar customer. */
+interface Customer {
+    id: string;
+    object: 'customer';
+    name: string;
+    email: string;
+    sentiment: string;
+    status: string;
+    tags: string[];
+    notes: string | null;
+    customFields: Record<string, unknown>;
+    ticketCount: number;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** A cStar knowledge base article. */
+interface Article {
+    id: string;
+    object: 'article';
+    title: string;
+    slug: string | null;
+    excerpt: string | null;
+    content: string | null;
+    category: string;
+    status: 'draft' | 'published';
+    tags: string[];
+    notes: string | null;
+    viewCount: number;
+    useCount: number;
+    readTime: string;
+    isPublic: boolean;
+    publishedAt: string | null;
+    metaDescription: string | null;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/** 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';
+/** 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: 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>;
+
+/** Thrown when webhook signature verification fails. */
+declare class WebhookSignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a webhook signature and parse the event (synchronous, Node.js only).
+ *
+ * Uses Node.js `crypto` module for timing-safe HMAC comparison.
+ * For browser/edge environments, use `constructEventAsync()`.
+ *
+ * @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 constructEvent(rawBody: string, signature: string, secret: string): WebhookEvent;
+/**
+ * Verify a webhook signature and parse the event (async, works everywhere).
+ *
+ * Uses the Web Crypto API — compatible with browsers, Deno, Cloudflare Workers,
+ * and Node.js 18+.
+ *
+ * @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 (synchronous, Node.js only).
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+declare function verifySignature(rawBody: string, signature: string, secret: string): boolean;
+/**
+ * Verify an HMAC-SHA256 signature (async, works everywhere).
+ * Uses the Web Crypto API with constant-time comparison.
+ */
+declare function verifySignatureAsync(rawBody: string, signature: string, secret: string): Promise<boolean>;
+
+export { type WebhookEvent, WebhookSignatureVerificationError, constructEvent, constructEventAsync, verifySignature, verifySignatureAsync };

package/dist/webhook/index.js

@@ -0,0 +1,62 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/webhook/index.ts
+var WebhookSignatureVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    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) {
+    throw new WebhookSignatureVerificationError(
+      "Webhook signature verification failed. Ensure you are using the raw request body and the correct endpoint 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(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(rawBody));
+  const expected = "sha256=" + Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  if (signature.length !== expected.length) return false;
+  let result = 0;
+  for (let i = 0; i < signature.length; i++) {
+    result |= signature.charCodeAt(i) ^ expected.charCodeAt(i);
+  }
+  return result === 0;
+}
+export {
+  WebhookSignatureVerificationError,
+  constructEvent,
+  constructEventAsync,
+  verifySignature,
+  verifySignatureAsync
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@cstar.help/js",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the cStar customer support platform",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./chat": {
+      "import": {
+        "types": "./dist/chat/index.d.ts",
+        "default": "./dist/chat/index.js"
+      },
+      "require": {
+        "types": "./dist/chat/index.d.cts",
+        "default": "./dist/chat/index.cjs"
+      }
+    },
+    "./library": {
+      "import": {
+        "types": "./dist/library/index.d.ts",
+        "default": "./dist/library/index.js"
+      },
+      "require": {
+        "types": "./dist/library/index.d.cts",
+        "default": "./dist/library/index.cjs"
+      }
+    },
+    "./webhook": {
+      "import": {
+        "types": "./dist/webhook/index.d.ts",
+        "default": "./dist/webhook/index.js"
+      },
+      "require": {
+        "types": "./dist/webhook/index.d.cts",
+        "default": "./dist/webhook/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "cstar",
+    "customer-support",
+    "sdk",
+    "api",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}