@cstar.help/js 0.1.0

package/dist/index.cjs

@@ -0,0 +1,364 @@
+"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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CStarAuthenticationError: () => CStarAuthenticationError,
+  CStarClient: () => CStarClient,
+  CStarError: () => CStarError,
+  CStarNotFoundError: () => CStarNotFoundError,
+  CStarRateLimitError: () => CStarRateLimitError,
+  CStarValidationError: () => CStarValidationError,
+  ErrorType: () => ErrorType
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CStarAuthenticationError,
+  CStarClient,
+  CStarError,
+  CStarNotFoundError,
+  CStarRateLimitError,
+  CStarValidationError,
+  ErrorType
+});