@forjio/suppuo 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @forjio/suppuo
+
+Typed JS/TS client for the [suppuo.com](https://suppuo.com) helpdesk REST API.
+
+```bash
+npm install @forjio/suppuo
+```
+
+```ts
+import { SuppuoClient } from "@forjio/suppuo";
+
+// Bearer token from `token` or the SUPPUO_TOKEN env var.
+const client = new SuppuoClient({ token: process.env.SUPPUO_TOKEN! });
+
+// Agent workspace surface
+const { tickets, counts } = await client.tickets.list({ status: "open" });
+const ticket = await client.tickets.get(tickets[0].id);
+await client.tickets.reply(ticket.id, { body: "On it!", isInternal: false });
+await client.tickets.update(ticket.id, { status: "resolved" });
+
+// Canned replies
+await client.cannedReplies.create({ title: "Refund policy", body: "…" });
+
+// Public (requester) surface — no token required
+const { accessToken } = await client.public.submitTicket({
+  accountId: "acc_…",
+  subject: "Order question",
+  body: "Where is my order?",
+  email: "customer@example.com",
+});
+const view = await client.public.getTicket(accessToken);
+await client.public.replyTicket(accessToken, { body: "Any update?" });
+```
+
+Errors throw `SuppuoError` carrying the API envelope's `error.code`
+(`NOT_FOUND`, `VALIDATION_ERROR`, `AUTH_REQUIRED`, …), the HTTP status,
+and the `meta.requestId`.
+
+See [suppuo.com/docs/sdk/js](https://suppuo.com/docs/sdk/js) for the
+full method reference.
+
+## Family
+
+Sister to:
+- [`forjio-suppuo`](https://pypi.org/project/forjio-suppuo/) (Python)
+- [`hachimi-cat/suppuo-go`](https://github.com/hachimi-cat/suppuo-go) (Go)

package/dist/index.cjs

@@ -0,0 +1,167 @@
+"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 index_exports = {};
+__export(index_exports, {
+  SuppuoClient: () => SuppuoClient,
+  SuppuoError: () => SuppuoError
+});
+module.exports = __toCommonJS(index_exports);
+var SuppuoError = class extends Error {
+  /** HTTP status (0 for transport-level failures). */
+  status;
+  /** Envelope `error.code` (UPPER_SNAKE_CASE) or an SDK-side code
+   *  (`NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`). */
+  code;
+  requestId;
+  param;
+  constructor(status, code, message, requestId, param) {
+    super(message);
+    this.name = "SuppuoError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.param = param;
+  }
+};
+var SuppuoClient = class {
+  token;
+  baseUrl;
+  timeoutMs;
+  constructor(opts = {}) {
+    this.token = opts.token ?? process.env.SUPPUO_TOKEN ?? void 0;
+    this.baseUrl = (opts.baseUrl ?? "https://suppuo.com").replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(args) {
+    const url = new URL(this.baseUrl + args.path);
+    for (const [k, v] of Object.entries(args.query ?? {})) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const headers = { Accept: "application/json" };
+    if (!args.noAuth) {
+      if (!this.token) {
+        throw new SuppuoError(
+          0,
+          "AUTH_REQUIRED",
+          "No token configured. Pass `token` or set SUPPUO_TOKEN."
+        );
+      }
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (args.body !== void 0) headers["Content-Type"] = "application/json";
+    let res;
+    try {
+      res = await fetch(url, {
+        method: args.method,
+        headers,
+        body: args.body !== void 0 ? JSON.stringify(args.body) : void 0,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (e) {
+      if (e instanceof Error && e.name === "TimeoutError") {
+        throw new SuppuoError(0, "TIMEOUT", `request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new SuppuoError(0, "NETWORK_ERROR", e instanceof Error ? e.message : String(e));
+    }
+    let envelope;
+    try {
+      envelope = await res.json();
+    } catch {
+      throw new SuppuoError(res.status, "INVALID_RESPONSE", `non-JSON response (HTTP ${res.status})`);
+    }
+    if (!res.ok || envelope.error) {
+      const err = envelope.error;
+      throw new SuppuoError(
+        res.status,
+        err?.code ?? "UNKNOWN",
+        err?.message ?? `HTTP ${res.status}`,
+        envelope.meta?.requestId,
+        err?.param
+      );
+    }
+    return envelope.data;
+  }
+  // ─── Tickets (agent workspace surface, Bearer auth) ───────────────
+  tickets = {
+    /** GET /api/v1/tickets — newest-activity-first, with per-status counts. */
+    list: (params) => this.request({
+      method: "GET",
+      path: "/api/v1/tickets",
+      query: { status: params?.status, limit: params?.limit }
+    }),
+    /** GET /api/v1/tickets/:id — full ticket incl. message thread. */
+    get: (id) => this.request({ method: "GET", path: `/api/v1/tickets/${encodeURIComponent(id)}` }),
+    /** POST /api/v1/tickets — agent-logged ticket (e.g. arrived via WhatsApp). */
+    create: (input) => this.request({ method: "POST", path: "/api/v1/tickets", body: input }),
+    /** POST /api/v1/tickets/:id/messages — agent reply (or internal note). */
+    reply: (id, input) => this.request({
+      method: "POST",
+      path: `/api/v1/tickets/${encodeURIComponent(id)}/messages`,
+      body: input
+    }),
+    /** PATCH /api/v1/tickets/:id — status / priority / assignee. */
+    update: (id, patch) => this.request({
+      method: "PATCH",
+      path: `/api/v1/tickets/${encodeURIComponent(id)}`,
+      body: patch
+    })
+  };
+  // ─── Canned replies ────────────────────────────────────────────────
+  cannedReplies = {
+    /** GET /api/v1/canned-replies */
+    list: () => this.request({ method: "GET", path: "/api/v1/canned-replies" }),
+    /** POST /api/v1/canned-replies */
+    create: (input) => this.request({ method: "POST", path: "/api/v1/canned-replies", body: input }),
+    /** PATCH /api/v1/canned-replies/:id */
+    update: (id, patch) => this.request({
+      method: "PATCH",
+      path: `/api/v1/canned-replies/${encodeURIComponent(id)}`,
+      body: patch
+    }),
+    /** DELETE /api/v1/canned-replies/:id */
+    delete: (id) => this.request({ method: "DELETE", path: `/api/v1/canned-replies/${encodeURIComponent(id)}` })
+  };
+  // ─── Public (requester-facing, unauthenticated) ────────────────────
+  public = {
+    /** POST /api/v1/public/tickets — submit to a workspace's hosted form.
+     *  The returned `accessToken` is the requester's only credential. */
+    submitTicket: (input) => this.request({ method: "POST", path: "/api/v1/public/tickets", body: input, noAuth: true }),
+    /** GET /api/v1/public/tickets/:accessToken — tokenized status view
+     *  (public messages only; internal notes are never exposed). */
+    getTicket: (accessToken) => this.request({
+      method: "GET",
+      path: `/api/v1/public/tickets/${encodeURIComponent(accessToken)}`,
+      noAuth: true
+    }),
+    /** POST /api/v1/public/tickets/:accessToken/messages — requester reply. */
+    replyTicket: (accessToken, input) => this.request({
+      method: "POST",
+      path: `/api/v1/public/tickets/${encodeURIComponent(accessToken)}/messages`,
+      body: input,
+      noAuth: true
+    })
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SuppuoClient,
+  SuppuoError
+});

package/dist/index.d.cts

@@ -0,0 +1,199 @@
+/**
+ * Suppuo SDK — typed JS/TS client for the suppuo.com REST API.
+ * Sister to `forjio-suppuo` (Python) and `hachimi-cat/suppuo-go` (Go).
+ *
+ * Auth = Bearer JWT (a Huudis-minted access token). Pass `token` or set
+ * `SUPPUO_TOKEN`. The `public.*` surface (requester-facing hosted-form
+ * endpoints) needs no token at all.
+ *
+ * Every response rides the Forjio envelope `{ data, error, meta }`;
+ * the client unwraps it and throws `SuppuoError` (with the envelope's
+ * `error.code`) on failure.
+ */
+interface ApiEnvelope<T> {
+    data: T | null;
+    error: {
+        code: string;
+        message: string;
+        param?: string;
+        docUrl?: string;
+    } | null;
+    meta?: {
+        requestId: string;
+        timestamp: string;
+        cursor?: string | null;
+        hasMore?: boolean;
+    };
+}
+declare class SuppuoError extends Error {
+    /** HTTP status (0 for transport-level failures). */
+    readonly status: number;
+    /** Envelope `error.code` (UPPER_SNAKE_CASE) or an SDK-side code
+     *  (`NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`). */
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly param: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string, param?: string);
+}
+type TicketStatus = 'open' | 'pending' | 'resolved' | 'closed';
+type TicketPriority = 'low' | 'normal' | 'high' | 'urgent';
+type TicketChannel = 'web' | 'email' | 'whatsapp';
+interface Ticket {
+    id: string;
+    accountId: string;
+    number: number;
+    subject: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    channel: TicketChannel;
+    requesterEmail: string | null;
+    requesterName: string | null;
+    requesterPhone?: string | null;
+    assigneeSub: string | null;
+    accessToken: string;
+    lastMessageAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TicketMessage {
+    id: string;
+    ticketId: string;
+    authorType: 'agent' | 'requester';
+    authorSub?: string | null;
+    authorName: string | null;
+    body: string;
+    isInternal: boolean;
+    createdAt: string;
+}
+interface TicketWithMessages extends Ticket {
+    messages: TicketMessage[];
+}
+interface TicketList {
+    tickets: Ticket[];
+    /** Per-status counts for the whole workspace, e.g. `{ open: 3, pending: 1 }`. */
+    counts: Partial<Record<TicketStatus, number>>;
+}
+interface CannedReply {
+    id: string;
+    accountId: string;
+    title: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PublicTicketView {
+    number: number;
+    subject: string;
+    status: TicketStatus;
+    createdAt: string;
+    messages: Array<{
+        id: string;
+        authorType: 'agent' | 'requester';
+        authorName: string | null;
+        body: string;
+        createdAt: string;
+    }>;
+}
+interface SuppuoClientOptions {
+    /** Bearer access token (Huudis-minted JWT). Defaults to `SUPPUO_TOKEN`.
+     *  Optional — the `public.*` surface works without one. */
+    token?: string;
+    /** Base URL override. Default `https://suppuo.com`. */
+    baseUrl?: string;
+    /** Per-request fetch timeout. Default 30s. */
+    timeoutMs?: number;
+}
+interface FetchArgs {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    /** Public endpoints skip the Authorization header entirely. */
+    noAuth?: boolean;
+}
+declare class SuppuoClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(opts?: SuppuoClientOptions);
+    request<T>(args: FetchArgs): Promise<T>;
+    readonly tickets: {
+        /** GET /api/v1/tickets — newest-activity-first, with per-status counts. */
+        list: (params?: {
+            status?: TicketStatus | "all";
+            limit?: number;
+        }) => Promise<TicketList>;
+        /** GET /api/v1/tickets/:id — full ticket incl. message thread. */
+        get: (id: string) => Promise<TicketWithMessages>;
+        /** POST /api/v1/tickets — agent-logged ticket (e.g. arrived via WhatsApp). */
+        create: (input: {
+            subject: string;
+            body: string;
+            requesterEmail: string;
+            requesterName?: string;
+            priority?: TicketPriority;
+            channel?: TicketChannel;
+        }) => Promise<Ticket>;
+        /** POST /api/v1/tickets/:id/messages — agent reply (or internal note). */
+        reply: (id: string, input: {
+            body: string;
+            isInternal?: boolean;
+            authorName?: string;
+        }) => Promise<{
+            message: TicketMessage;
+            status: TicketStatus;
+        }>;
+        /** PATCH /api/v1/tickets/:id — status / priority / assignee. */
+        update: (id: string, patch: {
+            status?: TicketStatus;
+            priority?: TicketPriority;
+            assigneeSub?: string | null;
+        }) => Promise<Ticket>;
+    };
+    readonly cannedReplies: {
+        /** GET /api/v1/canned-replies */
+        list: () => Promise<{
+            cannedReplies: CannedReply[];
+        }>;
+        /** POST /api/v1/canned-replies */
+        create: (input: {
+            title: string;
+            body: string;
+        }) => Promise<CannedReply>;
+        /** PATCH /api/v1/canned-replies/:id */
+        update: (id: string, patch: {
+            title?: string;
+            body?: string;
+        }) => Promise<CannedReply>;
+        /** DELETE /api/v1/canned-replies/:id */
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly public: {
+        /** POST /api/v1/public/tickets — submit to a workspace's hosted form.
+         *  The returned `accessToken` is the requester's only credential. */
+        submitTicket: (input: {
+            accountId: string;
+            subject: string;
+            body: string;
+            email: string;
+            name?: string;
+        }) => Promise<{
+            number: number;
+            accessToken: string;
+        }>;
+        /** GET /api/v1/public/tickets/:accessToken — tokenized status view
+         *  (public messages only; internal notes are never exposed). */
+        getTicket: (accessToken: string) => Promise<PublicTicketView>;
+        /** POST /api/v1/public/tickets/:accessToken/messages — requester reply. */
+        replyTicket: (accessToken: string, input: {
+            body: string;
+        }) => Promise<{
+            id: string;
+            status: TicketStatus;
+        }>;
+    };
+}
+
+export { type ApiEnvelope, type CannedReply, type PublicTicketView, SuppuoClient, type SuppuoClientOptions, SuppuoError, type Ticket, type TicketChannel, type TicketList, type TicketMessage, type TicketPriority, type TicketStatus, type TicketWithMessages };

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Suppuo SDK — typed JS/TS client for the suppuo.com REST API.
+ * Sister to `forjio-suppuo` (Python) and `hachimi-cat/suppuo-go` (Go).
+ *
+ * Auth = Bearer JWT (a Huudis-minted access token). Pass `token` or set
+ * `SUPPUO_TOKEN`. The `public.*` surface (requester-facing hosted-form
+ * endpoints) needs no token at all.
+ *
+ * Every response rides the Forjio envelope `{ data, error, meta }`;
+ * the client unwraps it and throws `SuppuoError` (with the envelope's
+ * `error.code`) on failure.
+ */
+interface ApiEnvelope<T> {
+    data: T | null;
+    error: {
+        code: string;
+        message: string;
+        param?: string;
+        docUrl?: string;
+    } | null;
+    meta?: {
+        requestId: string;
+        timestamp: string;
+        cursor?: string | null;
+        hasMore?: boolean;
+    };
+}
+declare class SuppuoError extends Error {
+    /** HTTP status (0 for transport-level failures). */
+    readonly status: number;
+    /** Envelope `error.code` (UPPER_SNAKE_CASE) or an SDK-side code
+     *  (`NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`). */
+    readonly code: string;
+    readonly requestId: string | undefined;
+    readonly param: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string, param?: string);
+}
+type TicketStatus = 'open' | 'pending' | 'resolved' | 'closed';
+type TicketPriority = 'low' | 'normal' | 'high' | 'urgent';
+type TicketChannel = 'web' | 'email' | 'whatsapp';
+interface Ticket {
+    id: string;
+    accountId: string;
+    number: number;
+    subject: string;
+    status: TicketStatus;
+    priority: TicketPriority;
+    channel: TicketChannel;
+    requesterEmail: string | null;
+    requesterName: string | null;
+    requesterPhone?: string | null;
+    assigneeSub: string | null;
+    accessToken: string;
+    lastMessageAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TicketMessage {
+    id: string;
+    ticketId: string;
+    authorType: 'agent' | 'requester';
+    authorSub?: string | null;
+    authorName: string | null;
+    body: string;
+    isInternal: boolean;
+    createdAt: string;
+}
+interface TicketWithMessages extends Ticket {
+    messages: TicketMessage[];
+}
+interface TicketList {
+    tickets: Ticket[];
+    /** Per-status counts for the whole workspace, e.g. `{ open: 3, pending: 1 }`. */
+    counts: Partial<Record<TicketStatus, number>>;
+}
+interface CannedReply {
+    id: string;
+    accountId: string;
+    title: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PublicTicketView {
+    number: number;
+    subject: string;
+    status: TicketStatus;
+    createdAt: string;
+    messages: Array<{
+        id: string;
+        authorType: 'agent' | 'requester';
+        authorName: string | null;
+        body: string;
+        createdAt: string;
+    }>;
+}
+interface SuppuoClientOptions {
+    /** Bearer access token (Huudis-minted JWT). Defaults to `SUPPUO_TOKEN`.
+     *  Optional — the `public.*` surface works without one. */
+    token?: string;
+    /** Base URL override. Default `https://suppuo.com`. */
+    baseUrl?: string;
+    /** Per-request fetch timeout. Default 30s. */
+    timeoutMs?: number;
+}
+interface FetchArgs {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+    /** Public endpoints skip the Authorization header entirely. */
+    noAuth?: boolean;
+}
+declare class SuppuoClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(opts?: SuppuoClientOptions);
+    request<T>(args: FetchArgs): Promise<T>;
+    readonly tickets: {
+        /** GET /api/v1/tickets — newest-activity-first, with per-status counts. */
+        list: (params?: {
+            status?: TicketStatus | "all";
+            limit?: number;
+        }) => Promise<TicketList>;
+        /** GET /api/v1/tickets/:id — full ticket incl. message thread. */
+        get: (id: string) => Promise<TicketWithMessages>;
+        /** POST /api/v1/tickets — agent-logged ticket (e.g. arrived via WhatsApp). */
+        create: (input: {
+            subject: string;
+            body: string;
+            requesterEmail: string;
+            requesterName?: string;
+            priority?: TicketPriority;
+            channel?: TicketChannel;
+        }) => Promise<Ticket>;
+        /** POST /api/v1/tickets/:id/messages — agent reply (or internal note). */
+        reply: (id: string, input: {
+            body: string;
+            isInternal?: boolean;
+            authorName?: string;
+        }) => Promise<{
+            message: TicketMessage;
+            status: TicketStatus;
+        }>;
+        /** PATCH /api/v1/tickets/:id — status / priority / assignee. */
+        update: (id: string, patch: {
+            status?: TicketStatus;
+            priority?: TicketPriority;
+            assigneeSub?: string | null;
+        }) => Promise<Ticket>;
+    };
+    readonly cannedReplies: {
+        /** GET /api/v1/canned-replies */
+        list: () => Promise<{
+            cannedReplies: CannedReply[];
+        }>;
+        /** POST /api/v1/canned-replies */
+        create: (input: {
+            title: string;
+            body: string;
+        }) => Promise<CannedReply>;
+        /** PATCH /api/v1/canned-replies/:id */
+        update: (id: string, patch: {
+            title?: string;
+            body?: string;
+        }) => Promise<CannedReply>;
+        /** DELETE /api/v1/canned-replies/:id */
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly public: {
+        /** POST /api/v1/public/tickets — submit to a workspace's hosted form.
+         *  The returned `accessToken` is the requester's only credential. */
+        submitTicket: (input: {
+            accountId: string;
+            subject: string;
+            body: string;
+            email: string;
+            name?: string;
+        }) => Promise<{
+            number: number;
+            accessToken: string;
+        }>;
+        /** GET /api/v1/public/tickets/:accessToken — tokenized status view
+         *  (public messages only; internal notes are never exposed). */
+        getTicket: (accessToken: string) => Promise<PublicTicketView>;
+        /** POST /api/v1/public/tickets/:accessToken/messages — requester reply. */
+        replyTicket: (accessToken: string, input: {
+            body: string;
+        }) => Promise<{
+            id: string;
+            status: TicketStatus;
+        }>;
+    };
+}
+
+export { type ApiEnvelope, type CannedReply, type PublicTicketView, SuppuoClient, type SuppuoClientOptions, SuppuoError, type Ticket, type TicketChannel, type TicketList, type TicketMessage, type TicketPriority, type TicketStatus, type TicketWithMessages };

package/dist/index.js

@@ -0,0 +1,141 @@
+// src/index.ts
+var SuppuoError = class extends Error {
+  /** HTTP status (0 for transport-level failures). */
+  status;
+  /** Envelope `error.code` (UPPER_SNAKE_CASE) or an SDK-side code
+   *  (`NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`). */
+  code;
+  requestId;
+  param;
+  constructor(status, code, message, requestId, param) {
+    super(message);
+    this.name = "SuppuoError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.param = param;
+  }
+};
+var SuppuoClient = class {
+  token;
+  baseUrl;
+  timeoutMs;
+  constructor(opts = {}) {
+    this.token = opts.token ?? process.env.SUPPUO_TOKEN ?? void 0;
+    this.baseUrl = (opts.baseUrl ?? "https://suppuo.com").replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(args) {
+    const url = new URL(this.baseUrl + args.path);
+    for (const [k, v] of Object.entries(args.query ?? {})) {
+      if (v !== void 0) url.searchParams.set(k, String(v));
+    }
+    const headers = { Accept: "application/json" };
+    if (!args.noAuth) {
+      if (!this.token) {
+        throw new SuppuoError(
+          0,
+          "AUTH_REQUIRED",
+          "No token configured. Pass `token` or set SUPPUO_TOKEN."
+        );
+      }
+      headers["Authorization"] = `Bearer ${this.token}`;
+    }
+    if (args.body !== void 0) headers["Content-Type"] = "application/json";
+    let res;
+    try {
+      res = await fetch(url, {
+        method: args.method,
+        headers,
+        body: args.body !== void 0 ? JSON.stringify(args.body) : void 0,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (e) {
+      if (e instanceof Error && e.name === "TimeoutError") {
+        throw new SuppuoError(0, "TIMEOUT", `request timed out after ${this.timeoutMs}ms`);
+      }
+      throw new SuppuoError(0, "NETWORK_ERROR", e instanceof Error ? e.message : String(e));
+    }
+    let envelope;
+    try {
+      envelope = await res.json();
+    } catch {
+      throw new SuppuoError(res.status, "INVALID_RESPONSE", `non-JSON response (HTTP ${res.status})`);
+    }
+    if (!res.ok || envelope.error) {
+      const err = envelope.error;
+      throw new SuppuoError(
+        res.status,
+        err?.code ?? "UNKNOWN",
+        err?.message ?? `HTTP ${res.status}`,
+        envelope.meta?.requestId,
+        err?.param
+      );
+    }
+    return envelope.data;
+  }
+  // ─── Tickets (agent workspace surface, Bearer auth) ───────────────
+  tickets = {
+    /** GET /api/v1/tickets — newest-activity-first, with per-status counts. */
+    list: (params) => this.request({
+      method: "GET",
+      path: "/api/v1/tickets",
+      query: { status: params?.status, limit: params?.limit }
+    }),
+    /** GET /api/v1/tickets/:id — full ticket incl. message thread. */
+    get: (id) => this.request({ method: "GET", path: `/api/v1/tickets/${encodeURIComponent(id)}` }),
+    /** POST /api/v1/tickets — agent-logged ticket (e.g. arrived via WhatsApp). */
+    create: (input) => this.request({ method: "POST", path: "/api/v1/tickets", body: input }),
+    /** POST /api/v1/tickets/:id/messages — agent reply (or internal note). */
+    reply: (id, input) => this.request({
+      method: "POST",
+      path: `/api/v1/tickets/${encodeURIComponent(id)}/messages`,
+      body: input
+    }),
+    /** PATCH /api/v1/tickets/:id — status / priority / assignee. */
+    update: (id, patch) => this.request({
+      method: "PATCH",
+      path: `/api/v1/tickets/${encodeURIComponent(id)}`,
+      body: patch
+    })
+  };
+  // ─── Canned replies ────────────────────────────────────────────────
+  cannedReplies = {
+    /** GET /api/v1/canned-replies */
+    list: () => this.request({ method: "GET", path: "/api/v1/canned-replies" }),
+    /** POST /api/v1/canned-replies */
+    create: (input) => this.request({ method: "POST", path: "/api/v1/canned-replies", body: input }),
+    /** PATCH /api/v1/canned-replies/:id */
+    update: (id, patch) => this.request({
+      method: "PATCH",
+      path: `/api/v1/canned-replies/${encodeURIComponent(id)}`,
+      body: patch
+    }),
+    /** DELETE /api/v1/canned-replies/:id */
+    delete: (id) => this.request({ method: "DELETE", path: `/api/v1/canned-replies/${encodeURIComponent(id)}` })
+  };
+  // ─── Public (requester-facing, unauthenticated) ────────────────────
+  public = {
+    /** POST /api/v1/public/tickets — submit to a workspace's hosted form.
+     *  The returned `accessToken` is the requester's only credential. */
+    submitTicket: (input) => this.request({ method: "POST", path: "/api/v1/public/tickets", body: input, noAuth: true }),
+    /** GET /api/v1/public/tickets/:accessToken — tokenized status view
+     *  (public messages only; internal notes are never exposed). */
+    getTicket: (accessToken) => this.request({
+      method: "GET",
+      path: `/api/v1/public/tickets/${encodeURIComponent(accessToken)}`,
+      noAuth: true
+    }),
+    /** POST /api/v1/public/tickets/:accessToken/messages — requester reply. */
+    replyTicket: (accessToken, input) => this.request({
+      method: "POST",
+      path: `/api/v1/public/tickets/${encodeURIComponent(accessToken)}/messages`,
+      body: input,
+      noAuth: true
+    })
+  };
+};
+export {
+  SuppuoClient,
+  SuppuoError
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@forjio/suppuo",
+  "version": "0.1.0",
+  "description": "Suppuo SDK — typed JS/TS client for the suppuo.com REST API. Sister to the Python + Go SDKs.",
+  "license": "UNLICENSED",
+  "private": false,
+  "author": "Forjio <support@forjio.com>",
+  "homepage": "https://suppuo.com/docs/sdk/js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hachimi-cat/saas-suppuo.git",
+    "directory": "sdks/js"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": ["suppuo", "forjio", "helpdesk", "tickets", "support", "sdk"],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}