@meridesk/node-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,303 @@
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs?: number;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+}
+/**
+ * Thin wrapper around the global `fetch` for talking to the Meridesk SDK API.
+ * Handles auth headers, JSON encoding/decoding, timeouts, and translating
+ * non-2xx responses into `MerideskAPIError`.
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: HttpClientOptions);
+    private buildUrl;
+    private request;
+    get<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * Configuration accepted by `new Meridesk(config)`.
+ */
+interface MerideskConfig {
+    /**
+     * Your Meridesk API key (starts with `mdk_live_`). Create one from
+     * Settings > API Keys in your Meridesk dashboard.
+     */
+    apiKey: string;
+    /**
+     * Your Meridesk identity verification secret, returned once alongside
+     * your API key when it was created/regenerated. Required only to use
+     * `meridesk.identity.generateUserHash()` for secure widget mode.
+     */
+    identitySecret?: string;
+    /**
+     * Override the Meridesk API base URL. Defaults to the production SDK API.
+     * Mainly useful for testing against a local/staging backend.
+     */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 15000. */
+    timeoutMs?: number;
+}
+interface MerideskWebsite {
+    id: string;
+    name: string;
+    subdomain: string;
+    accountId: string;
+}
+interface MerideskApiKeyInfo {
+    id: string;
+    name: string;
+    prefix: string;
+    last4: string;
+}
+interface MeResponse {
+    website: MerideskWebsite;
+    apiKey: MerideskApiKeyInfo;
+}
+interface Customer {
+    id?: string;
+    _id?: string;
+    name: string;
+    email: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    status?: 'active' | 'inactive' | 'lead' | 'prospect' | 'customer';
+    timezone?: string;
+    address?: string;
+    externalIds?: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface UpsertCustomerInput {
+    email: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    externalIds?: Record<string, string>;
+}
+interface UpdateCustomerInput {
+    name?: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    status?: Customer['status'];
+    externalIds?: Record<string, string>;
+}
+type TicketStatus = 'open' | 'pending' | 'closed' | 'resolved';
+type TicketPriority = 'low' | 'medium' | 'high' | 'urgent';
+interface TicketMessage {
+    id: string;
+    message: string;
+    user: string;
+    attachments?: string[];
+    createdOn: string;
+    sender: 'support' | 'customer' | 'system' | 'assistant' | 'user';
+}
+interface Ticket {
+    id: string;
+    _id?: string;
+    ticketNumber: string;
+    name: string;
+    email: string;
+    title: string;
+    message: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    assignee?: string | null;
+    createdOn: string;
+    updatedOn: string;
+    chat?: TicketMessage[];
+}
+interface CreateTicketInput {
+    /** Email of the customer this ticket belongs to. Created if it doesn't exist yet. */
+    email: string;
+    /** Display name for the customer, used if they need to be created. */
+    name?: string;
+    title: string;
+    message: string;
+    priority?: TicketPriority;
+}
+interface ListTicketsParams {
+    email?: string;
+    status?: TicketStatus;
+}
+interface ReplyToTicketInput {
+    message: string;
+    /** Defaults to 'support' (i.e. a reply sent from your backend). */
+    sender?: 'support' | 'customer';
+}
+interface ArticleTopic {
+    _id?: string;
+    title: string;
+    content: string;
+    coverImage?: string;
+    helpfulCount?: number;
+    notHelpfulCount?: number;
+}
+interface Article {
+    _id?: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    iconBg?: string;
+    topics: ArticleTopic[];
+}
+interface ArticleCategory {
+    _id?: string;
+    name: string;
+    articles: Article[];
+}
+interface ArticleSearchResult {
+    _id: string;
+    article: Article;
+    category: {
+        id: string;
+        name: string;
+    };
+}
+
+declare class ArticlesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all knowledge base categories (with their nested articles/topics) for this website. */
+    listCategories(): Promise<ArticleCategory[]>;
+    /** Full-text searches article titles/topics for this website. */
+    search(query: string): Promise<ArticleSearchResult[]>;
+}
+
+declare class CustomersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a customer if one doesn't exist for this email yet, or updates
+     * the provided fields on the existing one.
+     */
+    upsert(input: UpsertCustomerInput): Promise<Customer>;
+    /** Fetches a customer by email. */
+    get(email: string): Promise<Customer>;
+    /** Updates one or more fields on an existing customer. */
+    update(email: string, input: UpdateCustomerInput): Promise<Customer>;
+}
+
+/**
+ * Generates HMAC-SHA256 identity verification hashes for the Meridesk
+ * widget's "secure mode", entirely locally — no network call is made.
+ *
+ * This mirrors the identity verification pattern used by Intercom/Zendesk:
+ * your backend signs a stable identifier for the logged-in user (their
+ * email or internal user id) with the `identitySecret` from your Meridesk
+ * API key, and passes the resulting hash to the widget alongside that
+ * identifier. Meridesk recomputes the hash server-side to confirm the
+ * request really came from your backend.
+ */
+declare class IdentityResource {
+    private readonly identitySecret?;
+    constructor(identitySecret?: string | undefined);
+    /**
+     * Computes the identity hash for a given user identifier (typically the
+     * customer's email address).
+     *
+     * @throws {MerideskConfigError} if no `identitySecret` was provided when
+     * constructing the `Meridesk` client, or if `userId` is empty.
+     */
+    generateUserHash(userId: string): string;
+}
+
+declare class TicketsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a support ticket on behalf of a customer, identified by email.
+     * The customer is created automatically if they don't already exist.
+     */
+    create(input: CreateTicketInput): Promise<Ticket>;
+    /** Lists tickets for this website, optionally filtered by customer email and/or status. */
+    list(params?: ListTicketsParams): Promise<Ticket[]>;
+    /** Fetches a single ticket by id. */
+    get(ticketId: string): Promise<Ticket>;
+    /** Adds a reply to a ticket (defaults to a 'support' reply from your backend). */
+    reply(ticketId: string, input: ReplyToTicketInput): Promise<Ticket>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.north-america.meridesk.live/sdk/v1";
+/**
+ * Official Meridesk Node.js SDK client for backend integrations.
+ *
+ * @example
+ * ```ts
+ * import { Meridesk } from '@meridesk/node-sdk';
+ *
+ * const meridesk = new Meridesk({
+ *   apiKey: process.env.MERIDESK_API_KEY!,
+ *   identitySecret: process.env.MERIDESK_IDENTITY_SECRET, // optional, for secure widget mode
+ * });
+ *
+ * const ticket = await meridesk.tickets.create({
+ *   email: 'jane@example.com',
+ *   name: 'Jane Doe',
+ *   title: 'Refund request',
+ *   message: 'I would like a refund for order #1234.',
+ * });
+ * ```
+ */
+declare class Meridesk {
+    /** Generate secure widget identity verification hashes, computed locally. */
+    readonly identity: IdentityResource;
+    /** Create, fetch, and update customers. */
+    readonly customers: CustomersResource;
+    /** Create, list, fetch, and reply to support tickets. */
+    readonly tickets: TicketsResource;
+    /** List and search knowledge base articles. */
+    readonly articles: ArticlesResource;
+    private readonly http;
+    constructor(config: MerideskConfig);
+    /** Verifies the configured API key is valid and returns basic website/account info. */
+    me(): Promise<MeResponse>;
+}
+
+/**
+ * Base class for all errors thrown by the Meridesk SDK.
+ */
+declare class MerideskError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Meridesk client is misconfigured (missing/invalid
+ * credentials, missing required arguments, etc.) — always a local,
+ * pre-request error.
+ */
+declare class MerideskConfigError extends MerideskError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Meridesk API responds with a non-2xx status code.
+ */
+declare class MerideskAPIError extends MerideskError {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Parsed JSON response body, if any. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Thrown when a request to the Meridesk API fails for network reasons
+ * (timeout, DNS failure, connection reset, etc.) rather than an API error
+ * response.
+ */
+declare class MerideskConnectionError extends MerideskError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+export { type Article, type ArticleCategory, type ArticleSearchResult, type ArticleTopic, type CreateTicketInput, type Customer, DEFAULT_BASE_URL, type ListTicketsParams, type MeResponse, Meridesk, MerideskAPIError, type MerideskApiKeyInfo, type MerideskConfig, MerideskConfigError, MerideskConnectionError, MerideskError, type MerideskWebsite, type ReplyToTicketInput, type Ticket, type TicketMessage, type TicketPriority, type TicketStatus, type UpdateCustomerInput, type UpsertCustomerInput, Meridesk as default };

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs?: number;
+}
+interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+}
+/**
+ * Thin wrapper around the global `fetch` for talking to the Meridesk SDK API.
+ * Handles auth headers, JSON encoding/decoding, timeouts, and translating
+ * non-2xx responses into `MerideskAPIError`.
+ */
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: HttpClientOptions);
+    private buildUrl;
+    private request;
+    get<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+}
+
+/**
+ * Configuration accepted by `new Meridesk(config)`.
+ */
+interface MerideskConfig {
+    /**
+     * Your Meridesk API key (starts with `mdk_live_`). Create one from
+     * Settings > API Keys in your Meridesk dashboard.
+     */
+    apiKey: string;
+    /**
+     * Your Meridesk identity verification secret, returned once alongside
+     * your API key when it was created/regenerated. Required only to use
+     * `meridesk.identity.generateUserHash()` for secure widget mode.
+     */
+    identitySecret?: string;
+    /**
+     * Override the Meridesk API base URL. Defaults to the production SDK API.
+     * Mainly useful for testing against a local/staging backend.
+     */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 15000. */
+    timeoutMs?: number;
+}
+interface MerideskWebsite {
+    id: string;
+    name: string;
+    subdomain: string;
+    accountId: string;
+}
+interface MerideskApiKeyInfo {
+    id: string;
+    name: string;
+    prefix: string;
+    last4: string;
+}
+interface MeResponse {
+    website: MerideskWebsite;
+    apiKey: MerideskApiKeyInfo;
+}
+interface Customer {
+    id?: string;
+    _id?: string;
+    name: string;
+    email: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    status?: 'active' | 'inactive' | 'lead' | 'prospect' | 'customer';
+    timezone?: string;
+    address?: string;
+    externalIds?: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface UpsertCustomerInput {
+    email: string;
+    name?: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    externalIds?: Record<string, string>;
+}
+interface UpdateCustomerInput {
+    name?: string;
+    phone?: string;
+    company?: string;
+    position?: string;
+    status?: Customer['status'];
+    externalIds?: Record<string, string>;
+}
+type TicketStatus = 'open' | 'pending' | 'closed' | 'resolved';
+type TicketPriority = 'low' | 'medium' | 'high' | 'urgent';
+interface TicketMessage {
+    id: string;
+    message: string;
+    user: string;
+    attachments?: string[];
+    createdOn: string;
+    sender: 'support' | 'customer' | 'system' | 'assistant' | 'user';
+}
+interface Ticket {
+    id: string;
+    _id?: string;
+    ticketNumber: string;
+    name: string;
+    email: string;
+    title: string;
+    message: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    assignee?: string | null;
+    createdOn: string;
+    updatedOn: string;
+    chat?: TicketMessage[];
+}
+interface CreateTicketInput {
+    /** Email of the customer this ticket belongs to. Created if it doesn't exist yet. */
+    email: string;
+    /** Display name for the customer, used if they need to be created. */
+    name?: string;
+    title: string;
+    message: string;
+    priority?: TicketPriority;
+}
+interface ListTicketsParams {
+    email?: string;
+    status?: TicketStatus;
+}
+interface ReplyToTicketInput {
+    message: string;
+    /** Defaults to 'support' (i.e. a reply sent from your backend). */
+    sender?: 'support' | 'customer';
+}
+interface ArticleTopic {
+    _id?: string;
+    title: string;
+    content: string;
+    coverImage?: string;
+    helpfulCount?: number;
+    notHelpfulCount?: number;
+}
+interface Article {
+    _id?: string;
+    title: string;
+    description?: string;
+    icon?: string;
+    iconBg?: string;
+    topics: ArticleTopic[];
+}
+interface ArticleCategory {
+    _id?: string;
+    name: string;
+    articles: Article[];
+}
+interface ArticleSearchResult {
+    _id: string;
+    article: Article;
+    category: {
+        id: string;
+        name: string;
+    };
+}
+
+declare class ArticlesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all knowledge base categories (with their nested articles/topics) for this website. */
+    listCategories(): Promise<ArticleCategory[]>;
+    /** Full-text searches article titles/topics for this website. */
+    search(query: string): Promise<ArticleSearchResult[]>;
+}
+
+declare class CustomersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a customer if one doesn't exist for this email yet, or updates
+     * the provided fields on the existing one.
+     */
+    upsert(input: UpsertCustomerInput): Promise<Customer>;
+    /** Fetches a customer by email. */
+    get(email: string): Promise<Customer>;
+    /** Updates one or more fields on an existing customer. */
+    update(email: string, input: UpdateCustomerInput): Promise<Customer>;
+}
+
+/**
+ * Generates HMAC-SHA256 identity verification hashes for the Meridesk
+ * widget's "secure mode", entirely locally — no network call is made.
+ *
+ * This mirrors the identity verification pattern used by Intercom/Zendesk:
+ * your backend signs a stable identifier for the logged-in user (their
+ * email or internal user id) with the `identitySecret` from your Meridesk
+ * API key, and passes the resulting hash to the widget alongside that
+ * identifier. Meridesk recomputes the hash server-side to confirm the
+ * request really came from your backend.
+ */
+declare class IdentityResource {
+    private readonly identitySecret?;
+    constructor(identitySecret?: string | undefined);
+    /**
+     * Computes the identity hash for a given user identifier (typically the
+     * customer's email address).
+     *
+     * @throws {MerideskConfigError} if no `identitySecret` was provided when
+     * constructing the `Meridesk` client, or if `userId` is empty.
+     */
+    generateUserHash(userId: string): string;
+}
+
+declare class TicketsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a support ticket on behalf of a customer, identified by email.
+     * The customer is created automatically if they don't already exist.
+     */
+    create(input: CreateTicketInput): Promise<Ticket>;
+    /** Lists tickets for this website, optionally filtered by customer email and/or status. */
+    list(params?: ListTicketsParams): Promise<Ticket[]>;
+    /** Fetches a single ticket by id. */
+    get(ticketId: string): Promise<Ticket>;
+    /** Adds a reply to a ticket (defaults to a 'support' reply from your backend). */
+    reply(ticketId: string, input: ReplyToTicketInput): Promise<Ticket>;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.north-america.meridesk.live/sdk/v1";
+/**
+ * Official Meridesk Node.js SDK client for backend integrations.
+ *
+ * @example
+ * ```ts
+ * import { Meridesk } from '@meridesk/node-sdk';
+ *
+ * const meridesk = new Meridesk({
+ *   apiKey: process.env.MERIDESK_API_KEY!,
+ *   identitySecret: process.env.MERIDESK_IDENTITY_SECRET, // optional, for secure widget mode
+ * });
+ *
+ * const ticket = await meridesk.tickets.create({
+ *   email: 'jane@example.com',
+ *   name: 'Jane Doe',
+ *   title: 'Refund request',
+ *   message: 'I would like a refund for order #1234.',
+ * });
+ * ```
+ */
+declare class Meridesk {
+    /** Generate secure widget identity verification hashes, computed locally. */
+    readonly identity: IdentityResource;
+    /** Create, fetch, and update customers. */
+    readonly customers: CustomersResource;
+    /** Create, list, fetch, and reply to support tickets. */
+    readonly tickets: TicketsResource;
+    /** List and search knowledge base articles. */
+    readonly articles: ArticlesResource;
+    private readonly http;
+    constructor(config: MerideskConfig);
+    /** Verifies the configured API key is valid and returns basic website/account info. */
+    me(): Promise<MeResponse>;
+}
+
+/**
+ * Base class for all errors thrown by the Meridesk SDK.
+ */
+declare class MerideskError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Meridesk client is misconfigured (missing/invalid
+ * credentials, missing required arguments, etc.) — always a local,
+ * pre-request error.
+ */
+declare class MerideskConfigError extends MerideskError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Meridesk API responds with a non-2xx status code.
+ */
+declare class MerideskAPIError extends MerideskError {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Parsed JSON response body, if any. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Thrown when a request to the Meridesk API fails for network reasons
+ * (timeout, DNS failure, connection reset, etc.) rather than an API error
+ * response.
+ */
+declare class MerideskConnectionError extends MerideskError {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+export { type Article, type ArticleCategory, type ArticleSearchResult, type ArticleTopic, type CreateTicketInput, type Customer, DEFAULT_BASE_URL, type ListTicketsParams, type MeResponse, Meridesk, MerideskAPIError, type MerideskApiKeyInfo, type MerideskConfig, MerideskConfigError, MerideskConnectionError, MerideskError, type MerideskWebsite, type ReplyToTicketInput, type Ticket, type TicketMessage, type TicketPriority, type TicketStatus, type UpdateCustomerInput, type UpsertCustomerInput, Meridesk as default };