@cstar.help/js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,519 @@
+/** Configuration for the HTTP client. */
+interface ClientConfig {
+    apiKey: string;
+    teamId: string;
+    baseUrl?: string;
+    version?: string;
+    maxRetries?: number;
+    timeout?: number;
+}
+/** Options for a single request. */
+interface FetchOptions {
+    body?: unknown;
+    query?: Record<string, string | string[] | number | boolean | undefined>;
+    idempotencyKey?: string;
+}
+/**
+ * Low-level HTTP client for the cStar API.
+ * Handles authentication, retries, rate limiting, and error parsing.
+ */
+declare class HttpClient {
+    private readonly config;
+    /** Whether this client uses test mode keys. */
+    readonly environment: 'live' | 'test';
+    constructor(config: ClientConfig);
+    /**
+     * Make an authenticated request to the cStar API.
+     * Automatically retries on 5xx errors and rate limits.
+     */
+    request<T>(method: string, path: string, options?: FetchOptions): Promise<T>;
+    private buildUrl;
+    private buildHeaders;
+    /** Exponential backoff: 500ms, 1s, 2s, 4s... capped at 8s, plus jitter. */
+    private getBackoffDelay;
+    private sleep;
+}
+
+/** Metadata: string key-value pairs. Max 50 keys, 40-char keys, 500-char values. */
+type Metadata = Record<string, string>;
+/** Standard pagination parameters accepted by list endpoints. */
+interface PaginationParams {
+    page?: number;
+    pageSize?: number;
+}
+/** Pagination info returned in list responses. */
+interface PaginationInfo {
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+}
+/** API response envelope for single objects. */
+interface ApiResponse<T> {
+    success: true;
+    data: T;
+    meta: {
+        requestId: string;
+        timestamp: string;
+    };
+}
+/** API response envelope for lists with pagination. */
+interface ListResponse<T> {
+    success: true;
+    data: T[];
+    pagination: PaginationInfo;
+    meta: {
+        requestId: string;
+        timestamp: string;
+    };
+}
+/** Delete response body. */
+interface DeleteResponse {
+    deleted: true;
+    id: string;
+}
+/** Per-request options passed to resource methods. */
+interface RequestOptions {
+    /** Idempotency key for safe retries on POST/PATCH. */
+    idempotencyKey?: string;
+    /** Related resources to expand inline. */
+    expand?: 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;
+}
+/** Parameters for creating a message on a ticket. */
+interface MessageCreateParams {
+    content: string;
+    sender?: 'customer' | 'agent' | 'system';
+    senderId?: string;
+    senderName?: string;
+}
+
+/** 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;
+}
+/** Parameters for listing tickets. */
+interface TicketListParams extends PaginationParams {
+    status?: string;
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    customerId?: string;
+    assignedTo?: string;
+    search?: string;
+    expand?: string[];
+}
+/** Parameters for creating a ticket. */
+interface TicketCreateParams {
+    title: string;
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    status?: string;
+    customerId?: string;
+    customerName?: string;
+    tags?: string[];
+    notes?: string;
+    metadata?: Metadata;
+}
+/** Parameters for updating a ticket. */
+interface TicketUpdateParams {
+    title?: string;
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+    status?: string;
+    customerId?: string | null;
+    customerName?: string;
+    assignedTo?: string | null;
+    tags?: string[];
+    notes?: string;
+    metadata?: Record<string, string | null>;
+}
+
+/**
+ * Base resource class implementing standard CRUD operations.
+ * Resource-specific classes extend this with their own type parameters.
+ */
+declare abstract class BaseResource<TEntity, TListParams extends PaginationParams, TCreateParams, TUpdateParams> {
+    protected readonly client: HttpClient;
+    protected readonly basePath: string;
+    constructor(client: HttpClient, basePath: string);
+    /** List resources with optional filtering and pagination. */
+    list(params?: TListParams & RequestOptions): Promise<ListResponse<TEntity>>;
+    /** Get a single resource by ID. */
+    get(id: string, options?: RequestOptions): Promise<ApiResponse<TEntity>>;
+    /** Create a new resource. */
+    create(params: TCreateParams, options?: RequestOptions): Promise<ApiResponse<TEntity>>;
+    /** Update an existing resource. */
+    update(id: string, params: TUpdateParams, options?: RequestOptions): Promise<ApiResponse<TEntity>>;
+    /** Delete a resource by ID. */
+    del(id: string): Promise<ApiResponse<DeleteResponse>>;
+    /**
+     * Auto-paginating async iterator that yields every item across all pages.
+     *
+     * ```typescript
+     * for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' })) {
+     *   console.log(ticket.title);
+     * }
+     * ```
+     */
+    listAutoPaginating(params?: Omit<TListParams, 'page'> & RequestOptions): AsyncIterable<TEntity>;
+    /** Convert params to string values for query string serialization. */
+    protected serializeQuery(params: Record<string, unknown>): Record<string, string | string[] | undefined>;
+}
+
+/** Manage ticket messages as a sub-resource. */
+declare class TicketMessagesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /** List all messages on a ticket. */
+    list(ticketId: string): Promise<ApiResponse<Message[]>>;
+    /** Add a message to a ticket. */
+    create(ticketId: string, params: MessageCreateParams, options?: RequestOptions): Promise<ApiResponse<Message>>;
+}
+/** Manage support tickets. */
+declare class TicketsResource extends BaseResource<Ticket, TicketListParams, TicketCreateParams, TicketUpdateParams> {
+    /** Sub-resource for ticket messages. */
+    readonly messages: TicketMessagesResource;
+    constructor(client: HttpClient);
+}
+
+/** 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;
+}
+/** Parameters for listing customers. */
+interface CustomerListParams extends PaginationParams {
+    status?: string;
+    sentiment?: string;
+    search?: string;
+    tag?: string;
+    expand?: string[];
+}
+/** Parameters for creating a customer. */
+interface CustomerCreateParams {
+    name: string;
+    email: string;
+    sentiment?: string;
+    status?: string;
+    tags?: string[];
+    notes?: string;
+    customFields?: Record<string, unknown>;
+    metadata?: Metadata;
+}
+/** Parameters for updating a customer. */
+interface CustomerUpdateParams {
+    name?: string;
+    email?: string;
+    sentiment?: string;
+    status?: string;
+    tags?: string[];
+    notes?: string;
+    customFields?: Record<string, unknown>;
+    metadata?: Record<string, string | null>;
+}
+
+/** Manage customers. */
+declare class CustomersResource extends BaseResource<Customer, CustomerListParams, CustomerCreateParams, CustomerUpdateParams> {
+    constructor(client: HttpClient);
+}
+
+/** 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;
+}
+/** Parameters for listing articles. */
+interface ArticleListParams extends PaginationParams {
+    category?: string;
+    status?: 'draft' | 'published';
+    isPublic?: boolean;
+    search?: string;
+    tag?: string;
+    expand?: string[];
+}
+/** Parameters for creating an article. */
+interface ArticleCreateParams {
+    title: string;
+    content?: string;
+    excerpt?: string;
+    category?: string;
+    status?: 'draft' | 'published';
+    tags?: string[];
+    notes?: string;
+    isPublic?: boolean;
+    slug?: string;
+    metaDescription?: string;
+    metadata?: Metadata;
+}
+/** Parameters for updating an article. */
+interface ArticleUpdateParams {
+    title?: string;
+    content?: string;
+    excerpt?: string;
+    category?: string;
+    status?: 'draft' | 'published';
+    tags?: string[];
+    notes?: string;
+    isPublic?: boolean;
+    slug?: string;
+    metaDescription?: string;
+    metadata?: Record<string, string | null>;
+}
+
+/** Manage knowledge base articles. */
+declare class ArticlesResource extends BaseResource<Article, ArticleListParams, ArticleCreateParams, ArticleUpdateParams> {
+    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';
+/** 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>;
+
+/** A cStar webhook endpoint. */
+interface Webhook {
+    id: string;
+    object: 'webhook';
+    name: string;
+    url: string;
+    events: WebhookEventType[];
+    isActive: boolean;
+    isRestHooks: boolean;
+    includeFullObjects: boolean;
+    flatPayload: boolean;
+    lastTriggeredAt: string | null;
+    lastSuccessAt: string | null;
+    lastFailureAt: string | null;
+    consecutiveFailures: number;
+    autoDisabledAt: string | null;
+    autoDisableReason: string | null;
+    metadata: Metadata;
+    createdAt: string;
+    updatedAt: string;
+    /** Only returned on creation (POST). */
+    secret?: string;
+}
+/** Parameters for listing webhooks. */
+interface WebhookListParams extends PaginationParams {
+    active?: boolean;
+}
+/** Parameters for creating a webhook. */
+interface WebhookCreateParams {
+    name: string;
+    url: string;
+    events: WebhookEventType[];
+    isRestHooks?: boolean;
+    includeFullObjects?: boolean;
+    flatPayload?: boolean;
+    metadata?: Metadata;
+}
+/** Parameters for updating a webhook. */
+interface WebhookUpdateParams {
+    name?: string;
+    url?: string;
+    events?: WebhookEventType[];
+    isActive?: boolean;
+    includeFullObjects?: boolean;
+    flatPayload?: boolean;
+    metadata?: Record<string, string | null>;
+}
+/** Result of testing a webhook delivery. */
+interface WebhookTestResult {
+    deliveryId: string;
+    event: string;
+    url: string;
+    success: boolean;
+    status: number | null;
+    responseTimeMs: number;
+    error: string | null;
+}
+
+/** Manage webhook endpoints. */
+declare class WebhooksResource extends BaseResource<Webhook, WebhookListParams, WebhookCreateParams, WebhookUpdateParams> {
+    constructor(client: HttpClient);
+    /** Send a test delivery to a webhook endpoint. */
+    test(webhookId: string, params?: {
+        event?: WebhookEventType;
+    }): Promise<ApiResponse<WebhookTestResult>>;
+}
+
+/** Error type constants matching the cStar API. */
+declare const ErrorType: {
+    readonly AUTHENTICATION_ERROR: "authentication_error";
+    readonly INVALID_REQUEST_ERROR: "invalid_request_error";
+    readonly NOT_FOUND_ERROR: "not_found_error";
+    readonly RATE_LIMIT_ERROR: "rate_limit_error";
+    readonly API_ERROR: "api_error";
+};
+/** Shape of the error object returned by the cStar API. */
+interface ApiErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+    doc_url: string;
+    request_id?: string;
+}
+/** Base error class for all cStar API errors. */
+declare class CStarError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly docUrl: string;
+    readonly requestId?: string;
+    readonly statusCode: number;
+    constructor(statusCode: number, body: ApiErrorBody);
+}
+/** Thrown when authentication fails (401/403). */
+declare class CStarAuthenticationError extends CStarError {
+    constructor(statusCode: number, body: ApiErrorBody);
+}
+/** Thrown when rate limited (429). Includes retry timing. */
+declare class CStarRateLimitError extends CStarError {
+    readonly retryAfter: number;
+    constructor(statusCode: number, body: ApiErrorBody, retryAfter: number);
+}
+/** Thrown when a resource is not found (404). */
+declare class CStarNotFoundError extends CStarError {
+    constructor(statusCode: number, body: ApiErrorBody);
+}
+/** Thrown on invalid request parameters (400). */
+declare class CStarValidationError extends CStarError {
+    constructor(statusCode: number, body: ApiErrorBody);
+}
+
+/** Configuration for the CStarClient. */
+interface CStarClientConfig {
+    /** Your API key (sk_live_*, sk_test_*, pk_live_*, or pk_test_*). */
+    apiKey: string;
+    /** Your team ID. */
+    teamId: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+    /** API version header (defaults to 2026-03-01). */
+    version?: string;
+    /** Max retry attempts for failed requests (defaults to 3). */
+    maxRetries?: number;
+    /** Request timeout in ms (defaults to 30000). */
+    timeout?: number;
+}
+/**
+ * The cStar API client.
+ *
+ * ```typescript
+ * const cstar = new CStarClient({
+ *   apiKey: 'sk_test_abc123...',
+ *   teamId: 'your-team-id',
+ * });
+ *
+ * const { data } = await cstar.tickets.list({ status: 'open' });
+ * ```
+ */
+declare class CStarClient {
+    /** Manage support tickets. */
+    readonly tickets: TicketsResource;
+    /** Manage customers. */
+    readonly customers: CustomersResource;
+    /** Manage knowledge base articles. */
+    readonly articles: ArticlesResource;
+    /** Manage webhook endpoints. */
+    readonly webhooks: WebhooksResource;
+    private readonly client;
+    constructor(config: CStarClientConfig);
+    /** Whether this client is using test mode keys (sk_test_* or pk_test_*). */
+    get isTestMode(): boolean;
+}
+
+export { type ApiErrorBody, type ApiResponse, type Article, type ArticleCreateParams, type ArticleListParams, type ArticleUpdateParams, CStarAuthenticationError, CStarClient, type CStarClientConfig, CStarError, CStarNotFoundError, CStarRateLimitError, CStarValidationError, type Customer, type CustomerCreateParams, type CustomerListParams, type CustomerUpdateParams, type DeleteResponse, ErrorType, type ListResponse, type Message, type MessageCreateParams, type Metadata, type PaginationInfo, type PaginationParams, type RequestOptions, type Ticket, type TicketCreateParams, type TicketCustomerSummary, type TicketListParams, type TicketUpdateParams, type Webhook, type WebhookCreateParams, type WebhookEvent, type WebhookEventData, type WebhookEventType, type WebhookListParams, type WebhookTestResult, type WebhookUpdateParams };