@xalantis/sdk 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @xalantis/sdk
+
+Official JavaScript/TypeScript SDK for the Xalantis API.
+
+## Installation
+
+```bash
+npm install @xalantis/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Xalantis } from '@xalantis/sdk'
+
+const client = new Xalantis({
+  apiKey: 'xal_live_...',
+})
+```
+
+## Tickets
+
+### Create a ticket
+
+```typescript
+const { data: ticket } = await client.tickets.create({
+  subject: 'Login issue',
+  description: 'Cannot login since the latest update',
+  requester_email: 'user@example.com',
+  priority: 'high',
+  category_slug: 'technical-support', // optional
+})
+
+console.log(ticket.uuid, ticket.reference)
+```
+
+### List tickets
+
+```typescript
+const { data: tickets, meta } = await client.tickets.list({
+  status: 'open',
+  priority: 'high',
+  per_page: 10,
+  sort_by: 'created_at',
+  sort_dir: 'desc',
+})
+
+console.log(`${meta.total} tickets found`)
+```
+
+### Get a ticket
+
+```typescript
+const { data: ticket } = await client.tickets.get('ticket-uuid')
+```
+
+### Update a ticket
+
+```typescript
+await client.tickets.update('ticket-uuid', {
+  status: 'resolved',
+  priority: 'low',
+})
+```
+
+### Reply to a ticket
+
+```typescript
+await client.tickets.reply('ticket-uuid', {
+  content: 'This has been fixed in v2.1.0',
+})
+
+// Internal note (not visible to requester)
+await client.tickets.reply('ticket-uuid', {
+  content: 'Deployed hotfix to production',
+  is_internal: true,
+})
+```
+
+### List replies
+
+```typescript
+const { data: replies } = await client.tickets.listReplies('ticket-uuid')
+```
+
+## Error Handling
+
+```typescript
+import { Xalantis, XalantisError } from '@xalantis/sdk'
+
+try {
+  await client.tickets.create({ ... })
+} catch (error) {
+  if (error instanceof XalantisError) {
+    console.error(error.code)    // 'VALIDATION_ERROR'
+    console.error(error.message) // 'Validation failed.'
+    console.error(error.status)  // 422
+    console.error(error.details) // { subject: ['Required'] }
+  }
+}
+```
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  Ticket,
+  TicketPriority,
+  TicketStatus,
+  CreateTicketInput,
+  UpdateTicketInput,
+  TicketReply,
+} from '@xalantis/sdk'
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,338 @@
+/** Configuration for the Xalantis SDK client. */
+interface XalantisConfig {
+    /** Your Xalantis API key (e.g. `sk_live_...`). */
+    apiKey: string;
+    /** @internal For testing only. Defaults to https://xalantis.com */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000 (30s). */
+    timeout?: number;
+}
+/** Standard API response wrapping a single resource. */
+interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    message: string | null;
+}
+/** Paginated API response wrapping a list of resources. */
+interface PaginatedResponse<T> {
+    success: boolean;
+    data: T[];
+    /** Pagination metadata. */
+    meta: {
+        current_page: number;
+        per_page: number;
+        total: number;
+        last_page: number;
+        from: number | null;
+        to: number | null;
+    };
+    /** Pagination navigation links. */
+    links: {
+        first: string | null;
+        last: string | null;
+        prev: string | null;
+        next: string | null;
+    };
+    message: string | null;
+}
+/** API error response structure. */
+interface ApiError {
+    success: false;
+    error: {
+        /** Machine-readable error code (e.g. `VALIDATION_ERROR`, `NOT_FOUND`). */
+        code: string;
+        /** Human-readable error message. */
+        message: string;
+        /** Field-level validation errors, keyed by field name. */
+        details?: Record<string, string[]>;
+    };
+}
+/** Ticket priority levels. */
+type TicketPriority = 'low' | 'medium' | 'high' | 'urgent';
+/** Ticket lifecycle statuses. */
+type TicketStatus = 'new' | 'open' | 'pending' | 'on_hold' | 'resolved' | 'closed';
+/** Channel through which a ticket was created. */
+type TicketChannel = 'api' | 'email' | 'phone' | 'chat' | 'web' | 'widget';
+/** A support ticket. */
+interface Ticket {
+    /** Unique identifier (UUID v4). */
+    uuid: string;
+    /** Human-readable reference (e.g. `TK-000042`). */
+    reference: string;
+    /** Ticket subject line. */
+    subject: string;
+    /** Ticket description / body. */
+    description: string;
+    /** Current status. */
+    status: TicketStatus;
+    /** Priority level. */
+    priority: TicketPriority;
+    /** Channel through which the ticket was created. */
+    channel: TicketChannel;
+    /** Ticket category, if assigned. */
+    category: {
+        name: string;
+        slug: string;
+    } | null;
+    /** Person who submitted the ticket. */
+    requester: {
+        type: string;
+        name: string | null;
+        email: string | null;
+        phone: string | null;
+        contact_id: string | null;
+        client_id: string | null;
+    };
+    /** Agent assigned to the ticket. */
+    assignee: {
+        name: string;
+        email: string;
+    } | null;
+    /** Custom field values. */
+    custom_fields: Record<string, unknown> | null;
+    /** Tags attached to the ticket. */
+    tags: string[];
+    /** SLA due date (ISO 8601). */
+    due_at: string | null;
+    /** Creation timestamp (ISO 8601). */
+    created_at: string;
+    /** Last update timestamp (ISO 8601). */
+    updated_at: string;
+    /** When the ticket was resolved (ISO 8601). */
+    resolved_at: string | null;
+    /** When the ticket was closed (ISO 8601). */
+    closed_at: string | null;
+}
+/** Input for creating a new ticket. */
+interface CreateTicketInput {
+    /** Ticket subject (required, max 255 chars). */
+    subject: string;
+    /** Ticket description (required). */
+    description: string;
+    /** Email of the person reporting the issue (required). */
+    requester_email: string;
+    /** Name of the requester. */
+    requester_name?: string;
+    /** Priority level. Defaults to `medium`. */
+    priority?: TicketPriority;
+    /** Assign to a category by ID. */
+    category_id?: number;
+    /** Assign to a category by slug. */
+    category_slug?: string;
+    /** Channel source. Defaults to `api`. */
+    channel?: TicketChannel;
+    /** Custom field values. */
+    custom_fields?: Record<string, unknown>;
+}
+/** Input for updating an existing ticket. All fields are optional. */
+interface UpdateTicketInput {
+    subject?: string;
+    description?: string;
+    status?: TicketStatus;
+    priority?: TicketPriority;
+    category_id?: number;
+    category_slug?: string;
+    /** Assign to a specific agent by ID. */
+    assignee_id?: number;
+    /** SLA due date (ISO 8601). */
+    due_at?: string;
+    custom_fields?: Record<string, unknown>;
+}
+/** Parameters for listing/filtering tickets. */
+interface ListTicketsParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Results per page (default 15, max 100). */
+    per_page?: number;
+    /** Filter by status. */
+    status?: TicketStatus;
+    /** Filter by priority. */
+    priority?: TicketPriority;
+    /** Filter by assigned agent ID. */
+    assignee_id?: number;
+    /** Filter by requester email (exact match). */
+    requester_email?: string;
+    /** Full-text search on subject and description. */
+    search?: string;
+    /** Field to sort by. */
+    sort_by?: 'created_at' | 'updated_at' | 'priority' | 'status' | 'due_at' | 'reference';
+    /** Sort direction. */
+    sort_dir?: 'asc' | 'desc';
+}
+/** A reply or internal note on a ticket. */
+interface TicketReply {
+    /** Unique identifier (UUID v4). */
+    uuid: string;
+    /** Reply content (HTML or plain text). */
+    content: string;
+    /** Whether this is an internal note (not visible to the requester). */
+    is_internal: boolean;
+    /** Whether this reply was auto-generated by the system. */
+    is_automated: boolean;
+    /** Agent who posted the reply, if any. */
+    user: {
+        id: number;
+        full_name: string;
+        email: string;
+    } | null;
+    /** Creation timestamp (ISO 8601). */
+    created_at: string;
+    /** Last update timestamp (ISO 8601). */
+    updated_at: string;
+}
+/** Input for creating a reply on a ticket. */
+interface CreateTicketReplyInput {
+    /** Reply content (required). */
+    content: string;
+    /** Set to `true` for an internal note (not visible to the requester). */
+    is_internal?: boolean;
+}
+/** Parameters for listing replies. */
+interface ListTicketRepliesParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Results per page (default 50). */
+    per_page?: number;
+}
+
+/**
+ * Error thrown when the Xalantis API returns a non-success response.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.tickets.create({ ... })
+ * } catch (error) {
+ *   if (error instanceof XalantisError) {
+ *     console.error(error.code)    // 'VALIDATION_ERROR'
+ *     console.error(error.status)  // 422
+ *     console.error(error.details) // { subject: ['Required'] }
+ *   }
+ * }
+ * ```
+ */
+declare class XalantisError extends Error {
+    /** Machine-readable error code (e.g. `VALIDATION_ERROR`, `NOT_FOUND`, `UNAUTHORIZED`). */
+    code: string;
+    /** HTTP status code. */
+    status: number;
+    /** Field-level validation errors, keyed by field name. Only present for 422 responses. */
+    details?: Record<string, string[]>;
+    /** Value of `Retry-After` header when rate-limited (429). */
+    retryAfter?: number;
+    constructor(message: string, code: string, status: number, details?: Record<string, string[]>, retryAfter?: number);
+}
+/**
+ * Low-level HTTP client for the Xalantis API.
+ * Handles authentication, request building, and error mapping.
+ * @internal Use the `Xalantis` class instead.
+ */
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(config: XalantisConfig);
+    /** @internal Prevent accidental serialization of sensitive data. */
+    toJSON(): Record<string, unknown>;
+    private request;
+    /** Send a GET request and return a single resource. */
+    get<T>(path: string, params?: Record<string, unknown>): Promise<ApiResponse<T>>;
+    /** Send a GET request and return a paginated list. */
+    getPaginated<T>(path: string, params?: Record<string, unknown>): Promise<PaginatedResponse<T>>;
+    /** Send a POST request. */
+    post<T>(path: string, body: unknown): Promise<ApiResponse<T>>;
+    /** Send a PATCH request. */
+    patch<T>(path: string, body: unknown): Promise<ApiResponse<T>>;
+    /** Send a DELETE request. */
+    delete(path: string): Promise<ApiResponse<null>>;
+}
+
+declare class TicketsResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List tickets with optional filters and pagination.
+     *
+     * @example
+     * const tickets = await client.tickets.list({ status: 'open', per_page: 10 })
+     */
+    list(params?: ListTicketsParams): Promise<PaginatedResponse<Ticket>>;
+    /**
+     * Get a single ticket by UUID.
+     *
+     * @example
+     * const ticket = await client.tickets.get('uuid-here')
+     */
+    get(uuid: string): Promise<ApiResponse<Ticket>>;
+    /**
+     * Create a new ticket.
+     *
+     * @example
+     * const ticket = await client.tickets.create({
+     *   subject: 'Login issue',
+     *   description: 'Cannot login since update',
+     *   requester_email: 'user@example.com',
+     *   priority: 'high',
+     * })
+     */
+    create(input: CreateTicketInput): Promise<ApiResponse<Ticket>>;
+    /**
+     * Update an existing ticket.
+     *
+     * @example
+     * const ticket = await client.tickets.update('uuid-here', { status: 'resolved' })
+     */
+    update(uuid: string, input: UpdateTicketInput): Promise<ApiResponse<Ticket>>;
+    /**
+     * List replies for a ticket.
+     *
+     * @example
+     * const replies = await client.tickets.listReplies('uuid-here')
+     */
+    listReplies(ticketUuid: string, params?: ListTicketRepliesParams): Promise<PaginatedResponse<TicketReply>>;
+    /**
+     * Add a reply to a ticket.
+     *
+     * @example
+     * await client.tickets.reply('uuid-here', { content: 'Thanks for reporting!' })
+     */
+    reply(ticketUuid: string, input: CreateTicketReplyInput): Promise<ApiResponse<TicketReply>>;
+}
+
+/**
+ * Xalantis SDK Client.
+ *
+ * @example
+ * ```ts
+ * import { Xalantis } from '@xalantis/sdk'
+ *
+ * const client = new Xalantis({ apiKey: 'xal_live_...' })
+ *
+ * // Create a ticket
+ * const { data: ticket } = await client.tickets.create({
+ *   subject: 'Bug report',
+ *   description: 'Something is broken',
+ *   requester_email: 'user@example.com',
+ * })
+ *
+ * // List tickets
+ * const { data: tickets } = await client.tickets.list({ status: 'open' })
+ *
+ * // Get a ticket
+ * const { data: ticket } = await client.tickets.get('uuid-here')
+ *
+ * // Update a ticket
+ * await client.tickets.update('uuid-here', { status: 'resolved' })
+ *
+ * // Reply to a ticket
+ * await client.tickets.reply('uuid-here', { content: 'Fixed!' })
+ * ```
+ */
+declare class Xalantis {
+    private http;
+    /** Ticket management (create, list, get, update, reply). */
+    tickets: TicketsResource;
+    constructor(config: XalantisConfig);
+}
+
+export { type ApiError, type ApiResponse, type CreateTicketInput, type CreateTicketReplyInput, type ListTicketRepliesParams, type ListTicketsParams, type PaginatedResponse, type Ticket, type TicketChannel, type TicketPriority, type TicketReply, type TicketStatus, type UpdateTicketInput, Xalantis, type XalantisConfig, XalantisError };