@cstar.help/js 0.11.0 → 0.12.0

package/dist/webhook/index.d.ts

@@ -1,99 +1,398 @@
-/** 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;
+/** 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;
+    };
 }
-
-/** A cStar support ticket. */
-interface Ticket {
+/** Payload for `article.deleted` events. */
+interface ArticleDeletedPayload {
     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 {
+/** 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;
-    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 {
+/** 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;
-    object: 'article';
-    title: string;
-    slug: string | null;
-    excerpt: string | null;
-    content: string | null;
-    categoryId: string | null;
-    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';
+/** 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). */
@@ -105,19 +404,8 @@ 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];
+}
 
 /** Thrown when webhook signature verification fails. */
 declare class WebhookSignatureVerificationError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/js",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"description": "Official TypeScript SDK for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -76,6 +76,16 @@
 				"types": "./dist/proactive/index.d.cts",
 				"default": "./dist/proactive/index.cjs"
 			}
+		},
+		"./quickhelp": {
+			"import": {
+				"types": "./dist/quickhelp/index.d.ts",
+				"default": "./dist/quickhelp/index.js"
+			},
+			"require": {
+				"types": "./dist/quickhelp/index.d.cts",
+				"default": "./dist/quickhelp/index.cjs"
+			}
 		}
 	},
 	"files": [