@cstar.help/js 0.1.0

package/dist/index.js

@@ -0,0 +1,331 @@
+// src/errors.ts
+var ErrorType = {
+  AUTHENTICATION_ERROR: "authentication_error",
+  INVALID_REQUEST_ERROR: "invalid_request_error",
+  NOT_FOUND_ERROR: "not_found_error",
+  RATE_LIMIT_ERROR: "rate_limit_error",
+  API_ERROR: "api_error"
+};
+var CStarError = class extends Error {
+  constructor(statusCode, body) {
+    super(body.message);
+    this.name = "CStarError";
+    this.type = body.type;
+    this.code = body.code;
+    this.param = body.param;
+    this.docUrl = body.doc_url;
+    this.requestId = body.request_id;
+    this.statusCode = statusCode;
+  }
+};
+var CStarAuthenticationError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarAuthenticationError";
+  }
+};
+var CStarRateLimitError = class extends CStarError {
+  constructor(statusCode, body, retryAfter) {
+    super(statusCode, body);
+    this.name = "CStarRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var CStarNotFoundError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarNotFoundError";
+  }
+};
+var CStarValidationError = class extends CStarError {
+  constructor(statusCode, body) {
+    super(statusCode, body);
+    this.name = "CStarValidationError";
+  }
+};
+function parseError(statusCode, body, retryAfter) {
+  const errorBody = body?.error ?? {
+    type: ErrorType.API_ERROR,
+    code: "unknown_error",
+    message: `Request failed with status ${statusCode}`,
+    doc_url: "https://cstar.help/developers/api/errors"
+  };
+  switch (errorBody.type) {
+    case ErrorType.AUTHENTICATION_ERROR:
+      return new CStarAuthenticationError(statusCode, errorBody);
+    case ErrorType.RATE_LIMIT_ERROR:
+      return new CStarRateLimitError(statusCode, errorBody, retryAfter ?? 60);
+    case ErrorType.NOT_FOUND_ERROR:
+      return new CStarNotFoundError(statusCode, errorBody);
+    case ErrorType.INVALID_REQUEST_ERROR:
+      return new CStarValidationError(statusCode, errorBody);
+    default:
+      return new CStarError(statusCode, errorBody);
+  }
+}
+
+// src/client.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var DEFAULT_API_VERSION = "2026-03-01";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TIMEOUT = 3e4;
+var HttpClient = class {
+  constructor(config) {
+    this.config = {
+      apiKey: config.apiKey,
+      teamId: config.teamId,
+      baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      version: config.version ?? DEFAULT_API_VERSION,
+      maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT
+    };
+    this.environment = config.apiKey.startsWith("sk_test_") || config.apiKey.startsWith("pk_test_") ? "test" : "live";
+  }
+  /**
+   * Make an authenticated request to the cStar API.
+   * Automatically retries on 5xx errors and rate limits.
+   */
+  async request(method, path, options) {
+    const url = this.buildUrl(path, options?.query);
+    const headers = this.buildHeaders(options?.idempotencyKey);
+    const body = options?.body ? JSON.stringify(options.body) : void 0;
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      if (attempt > 0 && lastError) {
+        const delay = lastError instanceof CStarRateLimitError ? lastError.retryAfter * 1e3 : this.getBackoffDelay(attempt);
+        await this.sleep(delay);
+      }
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers,
+          body,
+          signal: AbortSignal.timeout(this.config.timeout)
+        });
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < this.config.maxRetries) continue;
+        throw lastError;
+      }
+      if (response.ok) {
+        return await response.json();
+      }
+      const errorBody = await response.json().catch(() => null);
+      const retryAfter = parseInt(response.headers.get("Retry-After") ?? "", 10) || void 0;
+      if (response.status < 500 && response.status !== 429) {
+        throw parseError(response.status, errorBody, retryAfter);
+      }
+      if (response.status === 429) {
+        lastError = parseError(429, errorBody, retryAfter);
+        if (attempt < this.config.maxRetries) continue;
+        throw lastError;
+      }
+      lastError = parseError(response.status, errorBody);
+      if (attempt < this.config.maxRetries) continue;
+      throw lastError;
+    }
+    throw lastError ?? new Error("Request failed after retries");
+  }
+  buildUrl(path, query) {
+    const base = `${this.config.baseUrl}/api/v1/teams/${this.config.teamId}${path}`;
+    if (!query) return base;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          params.append(`${key}[]`, v);
+        }
+      } else {
+        params.set(key, String(value));
+      }
+    }
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+  buildHeaders(idempotencyKey) {
+    const headers = {
+      "Authorization": `Bearer ${this.config.apiKey}`,
+      "Content-Type": "application/json",
+      "CStar-Version": this.config.version,
+      "User-Agent": `@cstar.help/js/${SDK_VERSION}`
+    };
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return headers;
+  }
+  /** Exponential backoff: 500ms, 1s, 2s, 4s... capped at 8s, plus jitter. */
+  getBackoffDelay(attempt) {
+    const base = Math.min(500 * Math.pow(2, attempt - 1), 8e3);
+    const jitter = Math.random() * 200;
+    return base + jitter;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/resources/base.ts
+var BaseResource = class {
+  constructor(client, basePath) {
+    this.client = client;
+    this.basePath = basePath;
+  }
+  /** List resources with optional filtering and pagination. */
+  async list(params) {
+    const { idempotencyKey: _, expand, ...rest } = params ?? {};
+    return this.client.request("GET", this.basePath, {
+      query: { ...this.serializeQuery(rest), expand }
+    });
+  }
+  /** Get a single resource by ID. */
+  async get(id, options) {
+    return this.client.request("GET", `${this.basePath}/${id}`, {
+      query: options?.expand ? { expand: options.expand } : void 0
+    });
+  }
+  /** Create a new resource. */
+  async create(params, options) {
+    return this.client.request("POST", this.basePath, {
+      body: params,
+      idempotencyKey: options?.idempotencyKey
+    });
+  }
+  /** Update an existing resource. */
+  async update(id, params, options) {
+    return this.client.request("PATCH", `${this.basePath}/${id}`, {
+      body: params,
+      idempotencyKey: options?.idempotencyKey
+    });
+  }
+  /** Delete a resource by ID. */
+  async del(id) {
+    return this.client.request(
+      "DELETE",
+      `${this.basePath}/${id}`
+    );
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAutoPaginating(params) {
+    let page = 1;
+    const pageSize = params?.pageSize;
+    while (true) {
+      const response = await this.list({ ...params, page, pageSize });
+      for (const item of response.data) {
+        yield item;
+      }
+      if (!response.pagination.hasMore) break;
+      page++;
+    }
+  }
+  /** Convert params to string values for query string serialization. */
+  serializeQuery(params) {
+    const result = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        result[key] = value.map(String);
+      } else if (typeof value === "boolean") {
+        result[key] = String(value);
+      } else {
+        result[key] = String(value);
+      }
+    }
+    return result;
+  }
+};
+
+// src/resources/tickets.ts
+var TicketMessagesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all messages on a ticket. */
+  async list(ticketId) {
+    return this.client.request(
+      "GET",
+      `/tickets/${ticketId}/messages`
+    );
+  }
+  /** Add a message to a ticket. */
+  async create(ticketId, params, options) {
+    return this.client.request(
+      "POST",
+      `/tickets/${ticketId}/messages`,
+      {
+        body: params,
+        idempotencyKey: options?.idempotencyKey
+      }
+    );
+  }
+};
+var TicketsResource = class extends BaseResource {
+  constructor(client) {
+    super(client, "/tickets");
+    this.messages = new TicketMessagesResource(client);
+  }
+};
+
+// src/resources/customers.ts
+var CustomersResource = class extends BaseResource {
+  constructor(client) {
+    super(client, "/customers");
+  }
+};
+
+// src/resources/articles.ts
+var ArticlesResource = class extends BaseResource {
+  constructor(client) {
+    super(client, "/articles");
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class extends BaseResource {
+  constructor(client) {
+    super(client, "/webhooks");
+  }
+  /** Send a test delivery to a webhook endpoint. */
+  async test(webhookId, params) {
+    return this.client.request(
+      "POST",
+      `/webhooks/${webhookId}/test`,
+      { body: params ?? {} }
+    );
+  }
+};
+
+// src/index.ts
+var CStarClient = class {
+  constructor(config) {
+    this.client = new HttpClient(config);
+    this.tickets = new TicketsResource(this.client);
+    this.customers = new CustomersResource(this.client);
+    this.articles = new ArticlesResource(this.client);
+    this.webhooks = new WebhooksResource(this.client);
+  }
+  /** Whether this client is using test mode keys (sk_test_* or pk_test_*). */
+  get isTestMode() {
+    return this.client.environment === "test";
+  }
+};
+export {
+  CStarAuthenticationError,
+  CStarClient,
+  CStarError,
+  CStarNotFoundError,
+  CStarRateLimitError,
+  CStarValidationError,
+  ErrorType
+};

package/dist/library/index.cjs

@@ -0,0 +1,97 @@
+"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/library/index.ts
+var library_exports = {};
+__export(library_exports, {
+  LibraryClient: () => LibraryClient
+});
+module.exports = __toCommonJS(library_exports);
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var LibraryClient = class {
+  constructor(config) {
+    this.resolvedTeamId = null;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+  }
+  /** List all public categories with article counts. */
+  async categories() {
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/categories`
+    );
+    return response.data;
+  }
+  /** List published articles, optionally filtered by category. */
+  async articles(params) {
+    const query = {};
+    if (params?.categorySlug) query.categorySlug = params.categorySlug;
+    if (params?.limit) query.limit = String(params.limit);
+    if (params?.offset) query.offset = String(params.offset);
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/articles`,
+      query
+    );
+    return response.data;
+  }
+  /** Get a single article by slug. */
+  async article(slug) {
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/articles/${slug}`
+    );
+    return response.data;
+  }
+  /**
+   * Full-text search across article titles, excerpts, and content.
+   * Returns matching articles with relevance ranking.
+   */
+  async search(query, params) {
+    const queryParams = {
+      q: query
+    };
+    if (params?.limit) queryParams.limit = String(params.limit);
+    return this.fetch(
+      `/api/library/${this.teamSlug}/search`,
+      queryParams
+    );
+  }
+  async fetch(path, query) {
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) params.set(key, value);
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const response = await globalThis.fetch(url, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
+      throw new Error(errorBody.error?.message ?? `Library API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LibraryClient
+});

package/dist/library/index.d.cts

@@ -0,0 +1,82 @@
+/** Configuration for the LibraryClient. */
+interface LibraryConfig {
+    /** Team slug (e.g., 'acme'). Identifies the knowledge base to query. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+}
+/** A published article in the public knowledge base. */
+interface LibraryArticle {
+    id: string;
+    team_id: string;
+    title: string;
+    slug: string;
+    excerpt: string;
+    content: string;
+    category: string;
+    tags: string[];
+    view_count: number;
+    published_at: string;
+    created_at: string;
+    updated_at: string;
+    meta_description?: string;
+}
+/** A category in the knowledge base. */
+interface Category {
+    id: string;
+    team_id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    sort_order: number;
+    is_public: boolean;
+    article_count: number;
+}
+/** Parameters for listing articles. */
+interface LibraryArticleListParams {
+    categorySlug?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Parameters for searching articles. */
+interface LibrarySearchParams {
+    limit?: number;
+}
+/** Search results. */
+interface LibrarySearchResult {
+    data: LibraryArticle[];
+    count: number;
+    query: string;
+}
+
+/**
+ * Public knowledge base client. No authentication required.
+ *
+ * ```typescript
+ * const library = new LibraryClient({ teamSlug: 'acme' });
+ * const categories = await library.categories();
+ * const results = await library.search('reset password');
+ * ```
+ */
+declare class LibraryClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private resolvedTeamId;
+    constructor(config: LibraryConfig);
+    /** List all public categories with article counts. */
+    categories(): Promise<Category[]>;
+    /** List published articles, optionally filtered by category. */
+    articles(params?: LibraryArticleListParams): Promise<LibraryArticle[]>;
+    /** Get a single article by slug. */
+    article(slug: string): Promise<LibraryArticle>;
+    /**
+     * Full-text search across article titles, excerpts, and content.
+     * Returns matching articles with relevance ranking.
+     */
+    search(query: string, params?: LibrarySearchParams): Promise<LibrarySearchResult>;
+    private fetch;
+}
+
+export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult };

package/dist/library/index.d.ts

@@ -0,0 +1,82 @@
+/** Configuration for the LibraryClient. */
+interface LibraryConfig {
+    /** Team slug (e.g., 'acme'). Identifies the knowledge base to query. */
+    teamSlug: string;
+    /** Override the base URL (defaults to https://app.cstar.help). */
+    baseUrl?: string;
+}
+/** A published article in the public knowledge base. */
+interface LibraryArticle {
+    id: string;
+    team_id: string;
+    title: string;
+    slug: string;
+    excerpt: string;
+    content: string;
+    category: string;
+    tags: string[];
+    view_count: number;
+    published_at: string;
+    created_at: string;
+    updated_at: string;
+    meta_description?: string;
+}
+/** A category in the knowledge base. */
+interface Category {
+    id: string;
+    team_id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    icon?: string;
+    color?: string;
+    sort_order: number;
+    is_public: boolean;
+    article_count: number;
+}
+/** Parameters for listing articles. */
+interface LibraryArticleListParams {
+    categorySlug?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Parameters for searching articles. */
+interface LibrarySearchParams {
+    limit?: number;
+}
+/** Search results. */
+interface LibrarySearchResult {
+    data: LibraryArticle[];
+    count: number;
+    query: string;
+}
+
+/**
+ * Public knowledge base client. No authentication required.
+ *
+ * ```typescript
+ * const library = new LibraryClient({ teamSlug: 'acme' });
+ * const categories = await library.categories();
+ * const results = await library.search('reset password');
+ * ```
+ */
+declare class LibraryClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private resolvedTeamId;
+    constructor(config: LibraryConfig);
+    /** List all public categories with article counts. */
+    categories(): Promise<Category[]>;
+    /** List published articles, optionally filtered by category. */
+    articles(params?: LibraryArticleListParams): Promise<LibraryArticle[]>;
+    /** Get a single article by slug. */
+    article(slug: string): Promise<LibraryArticle>;
+    /**
+     * Full-text search across article titles, excerpts, and content.
+     * Returns matching articles with relevance ranking.
+     */
+    search(query: string, params?: LibrarySearchParams): Promise<LibrarySearchResult>;
+    private fetch;
+}
+
+export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult };

package/dist/library/index.js

@@ -0,0 +1,72 @@
+// src/library/index.ts
+var DEFAULT_BASE_URL = "https://app.cstar.help";
+var LibraryClient = class {
+  constructor(config) {
+    this.resolvedTeamId = null;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+  }
+  /** List all public categories with article counts. */
+  async categories() {
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/categories`
+    );
+    return response.data;
+  }
+  /** List published articles, optionally filtered by category. */
+  async articles(params) {
+    const query = {};
+    if (params?.categorySlug) query.categorySlug = params.categorySlug;
+    if (params?.limit) query.limit = String(params.limit);
+    if (params?.offset) query.offset = String(params.offset);
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/articles`,
+      query
+    );
+    return response.data;
+  }
+  /** Get a single article by slug. */
+  async article(slug) {
+    const response = await this.fetch(
+      `/api/library/${this.teamSlug}/articles/${slug}`
+    );
+    return response.data;
+  }
+  /**
+   * Full-text search across article titles, excerpts, and content.
+   * Returns matching articles with relevance ranking.
+   */
+  async search(query, params) {
+    const queryParams = {
+      q: query
+    };
+    if (params?.limit) queryParams.limit = String(params.limit);
+    return this.fetch(
+      `/api/library/${this.teamSlug}/search`,
+      queryParams
+    );
+  }
+  async fetch(path, query) {
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) params.set(key, value);
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    const response = await globalThis.fetch(url, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
+      throw new Error(errorBody.error?.message ?? `Library API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+export {
+  LibraryClient
+};