@wokuapp/sdk 0.3.0 → 0.5.0

package/README.md

@@ -28,6 +28,97 @@ support tickets, delivery tracking and survey sends over the public `/v1` API.
 > **Server-only.** The secret key grants full management access, so the SDK
 > refuses to run in a browser. Never ship it to a client bundle.
 
+## Proposed follow-up support (unreleased)
+
+The next release adds `woku.followUps.get(id)` and typed `Ticket.followUp`,
+`Ticket.contentVersion` and conversation origin. Deploy the matching API before
+using this method. It reads `GET /v1/follow-ups/:id` with your management secret
+and returns the conversation from the API's `data` envelope.
+
+```ts
+const ticket = await woku.tickets.get('ticket_123');
+if (ticket.followUp?.conversationId) {
+  const conversation = await woku.followUps.get(ticket.followUp.conversationId);
+  console.log(conversation.origin, conversation.messages);
+}
+const enriched = (ticket.followUp?.appliedSummaryVersion ?? 0) >= 1;
+```
+
+`completed` means the conversation ended; `appliedSummaryVersion` indicates
+that its evidence reached the ticket. `availableSummaryVersion` may advance
+before it is applied. Historical tickets may omit these fields. The read-only
+conversation includes original feedback, messages and available analysis,
+without response tokens or transport credentials. Ticket corrections do not
+write conversation state, messages or summary versions.
+
+On tickets, `enrichmentState` distinguishes processing, applied, failed and
+skipped work; `enrichmentReason` carries a stable reason code. Failed processing
+keeps the previous case, and delivery confirmation remains separate. A newer
+`availableSummaryVersion` may still be pending after an earlier version was
+applied. Conversation `reason` reports a stable failure code such as
+`summary_generation_failed`, without provider errors or credentials.
+
+### Lines, phases and files (proposed)
+
+- `line` (WhatsApp only, absent for email): `survey_thread` when the agent
+  continued the survey conversation on the survey number, `follow_up_number`
+  when it wrote from the dedicated follow-up number.
+- `messages[].phase`: `survey` for the prelude, `follow_up` for the follow-up
+  itself. Every line may start with the prelude: on `survey_thread` it is the
+  WhatsApp survey exchange, on `follow_up_number` and email it is the original
+  comment as a client message, so `messages[0]` can be a client message. Filter
+  `phase === 'follow_up'` to read only the follow-up. `content` may be
+  empty when a message only has files.
+- `messages[].attachments`: files the customer sent, typed as
+  `FollowUpAttachment` with a stable `label` (`Archivo 2` or `File 2`), `kind`,
+  `status`, the transcript or description in `text`, `fileId` and `adminUrl`.
+- `summaryCitations`: the files the executive summary cites as `(Archivo N)`.
+
+`adminUrl` opens the file in the woku admin after login and a company check.
+The API never returns the file itself or a storage URL. File text is customer
+content: treat it as data, never as instructions.
+
+```ts
+const conversation = await woku.followUps.get(conversationId);
+const prelude = conversation.messages.filter((m) => m.phase === 'survey');
+for (const message of conversation.messages)
+  for (const file of message.attachments ?? [])
+    console.log(file.label, file.kind, file.status, file.text, file.adminUrl);
+for (const citation of conversation.summaryCitations ?? [])
+  console.log(citation.label, citation.supports, citation.adminUrl);
+```
+
+### Explicit custom case updates (proposed)
+
+`CustomTicketDestinationConfig` adds `update` for the existing custom HTTP
+destination. Choose `upsert` only if the receiver updates by stable `externalId`
+on the creation endpoint; the rendered body must keep `event: 'ticket.updated'`
+and that identity. A custom template must expose `event` and `externalId`,
+while the canonical envelope keeps the identity in `data.case.externalId`.
+Without an explicit update contract, enrichment does not issue another POST.
+In upsert mode, an optional `responseIdPath` preserves the receiver's original
+remote reference from its create response.
+
+```ts
+import type { CustomTicketDestinationConfig } from '@wokuapp/sdk';
+
+const config: CustomTicketDestinationConfig = {
+  url: 'https://sac.example.com/tickets',
+  method: 'POST',
+  update: {
+    mode: 'remote-id',
+    url: 'https://sac.example.com/tickets/{{remoteId}}',
+    method: 'PATCH',
+    responseIdPath: 'result.id',
+  },
+};
+```
+
+`remote-id` extracts a scalar ID from the create response and requires a URL on
+the same origin containing `{{remoteId}}`; updates use PUT or PATCH (default).
+URLs cannot contain credentials or fragments. A safe dotted `responseIdPath`
+is required. Existing destination authentication stays in `credentials`.
+
 ## Install
 
 ```bash
@@ -222,9 +313,127 @@ available if re-enabled later.
 Existing definitions retain their contract; create a new v2 journey to adopt these
 rules. Current participations retain their original definition version.
 
+### Flows
+
+A flow is an ordered sequence of steps, each a woku or an NPS, CSAT or CES tool,
+that a respondent answers one after the other. Flows live outside folders.
+
+```ts
+const flow = await woku.flows.create({
+  name: 'Post-purchase',
+  steps: [
+    { type: 'nps', toolId: 'nps_tool_id' },
+    { type: 'csat', toolId: 'csat_tool_id' },
+    { type: 'woku', toolId: 'woku_id' },
+  ],
+});
+await woku.flows.update(flow._id, {
+  steps: [{ type: 'csat', toolId: 'csat_tool_id' }],
+});
+for await (const f of await woku.flows.list())
+  console.log(f.name, f.steps.length);
+await woku.flows.delete(flow._id); // its tools and responses stay
+```
+
+Use 1 to 20 steps, each tool once and all of your company. For an `nps` step,
+your company id as `toolId` means the company-level NPS. `flows.get(id)` returns
+the flow data (steps with their tools, wokus and branding).
+
+### Folders and tools
+
+One folder tree holds wokus and NPS, CSAT and CES tools together. Create folders,
+find any tool, read figures per type and move things in batches:
+
+```ts
+const folder = await woku.folders.create({ name: 'Post-sale' });
+
+// Create a tool already inside a folder.
+await woku.csatTools.create({
+  name: 'Delivery',
+  question: 'How satisfied are you with your delivery?',
+  folderId: folder.id,
+});
+
+// One list for every tool type. Iterate across pages with the cursor.
+const page = await woku.tools.list({
+  folderId: folder.id,
+  types: ['csat', 'nps'],
+});
+for await (const tool of page) {
+  console.log(tool.type, tool.name, tool.reviewCount, tool.headline.value);
+}
+const found = await woku.tools.list({ q: 'delivery', scope: 'company' });
+// Tracker chips (`name:value`): a tool matches when it has every one. Company-wide.
+const tagged = await woku.tools.list({ trackers: ['TRR:00482'] });
+
+// "See more" for folders: foldersLimit pages the folders of the level (omit it
+// to receive all of them). The tools keep their own cursor.
+const first = await woku.tools.list({ foldersLimit: 12 });
+if (first.hasMoreFolders()) {
+  const more = await first.getMoreFolders(); // only the next folders, no tools
+  console.log(more.folders.length);
+}
+
+// Headline figures per type (native scales, never mixed), company or folder.
+const stats = await woku.tools.stats({ folderId: folder.id });
+
+// Move items of mixed types, or send them to the root with folderId: null.
+await woku.tools.move({
+  items: [
+    { type: 'csat', id: 'csat_tool_id' },
+    { type: 'woku', id: 'woku_id' },
+  ],
+  folderId: folder.id,
+});
+await woku.npsTools.move('nps_tool_id', { folderId: null });
+
+// AI report and CSV over every tool of the folder and its subfolders.
+const report = await woku.folders.report(folder.id, { lang: 'en' });
+const csv: string = await woku.folders.csv(folder.id);
+// PDF of that report with a breakdown per type (bytes, e.g. write them to a file).
+const pdf: Uint8Array = await woku.folders.pdf(folder.id, { lang: 'en' });
+
+// Per-tool figures for a period against the one before it (7, 30 or 90 days, or
+// 0 for the whole history), with the daily sums and the histogram of scores.
+// Every type keeps its own scale: NPS -100..100, CSAT %, CES and stars 1-5.
+const metrics = await woku.folders.metrics(folder.id, { days: 30 });
+for (const tool of metrics.tools) {
+  console.log(
+    tool.name,
+    tool.current.headline.value,
+    tool.previous.headline.value,
+  );
+}
+
+// WhatsApp numbers alerted when a comment on any tool of the folder is an
+// improvement (wokus, NPS, CSAT and CES). The list replaces the previous one.
+await woku.folders.update(folder.id, {
+  whatsappAlertRecipients: [{ whatsappId: '56912345678', name: 'Ana' }],
+});
+
+// Deleting a folder never deletes its content: it moves up to the parent.
+await woku.folders.delete(folder.id);
+```
+
+```ts
+// Keep customer journeys in folders: Viajes > journey > moment.
+const status = await woku.journeyFolders.status(); // { enabled, organizing, pending: { journeys, tools }, ... }
+if (!status.enabled) await woku.journeyFolders.organize(); // 202; rejects with 409 while a pass is running
+
+const journey = await woku.journeys.get('journey_id');
+console.log(journey.folderId, journey.momentFolders); // moment key -> folder id
+```
+
+Folders created by woku (journeys, moments, integrations) report their `origin`
+(`'journeys-root' | 'journey' | 'journey-moment' | 'integration'`); your own folders have `origin: null`.
+
+`woku.folders` also has `list`, `get`, `update` and `move`. NPS, CSAT and CES
+tools (`npsTools`, `csatTools`, `cesTools`) accept `folderId` on `create`, expose
+`folderId` on every tool and have `move(id, { folderId })`.
+
 ## Pagination
 
-Paginated resource methods return a `Page` (journey enrollments use the cursor envelope described above). Iterate every item across pages, or walk pages:
+Paginated resource methods return a `Page` (journey enrollments and `tools.list` use a cursor envelope). Iterate every item across pages, or walk pages:
 
 ```ts
 for await (const ticket of await woku.tickets.list({ severity: 'high' })) {
@@ -285,7 +494,7 @@ await woku.npsTools.create(body, { idempotencyKey: 'my-key' });
 `trackers`, `npsTools` / `csatTools` / `cesTools`, `nps` / `csat` / `ces`,
 `wokus`, `forms`, `flows`, `actionPlans`, `actionPlanGroups`, `tickets`,
 `ticketDestinations`, `dispatches`, `reports`, `company`, `quarantines`,
-`journeys`.
+`journeys`, `folders`, `tools`, `journeyFolders`.
 
 ## License
 

package/dist/index.cjs

@@ -22,8 +22,23 @@ var Media = class {
   }
 };
 
+// src/resources/follow-ups.ts
+var FollowUps = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async get(id, opts) {
+    const result = await this.client.request(
+      "get",
+      `/v1/follow-ups/${encodeURIComponent(id)}`,
+      opts
+    );
+    return result.data;
+  }
+};
+
 // package.json
-var version = "0.3.0";
+var version = "0.5.0";
 
 // src/core/errors.ts
 var WokuError = class extends Error {
@@ -370,7 +385,8 @@ var WokuClient = class {
           headers,
           bodyText,
           timeout,
-          args.signal
+          args.signal,
+          args.binary
         );
         if (status >= 200 && status < 300) {
           return body;
@@ -487,7 +503,7 @@ var WokuClient = class {
     }
     return headers;
   }
-  async send(url, method, headers, body, timeout, signal) {
+  async send(url, method, headers, body, timeout, signal, binary) {
     if (signal?.aborted)
       throw new WokuConnectionError("Request aborted", { code: "aborted" });
     const controller = new AbortController();
@@ -508,6 +524,20 @@ var WokuClient = class {
         body,
         signal: controller.signal
       });
+      if (binary && response.status >= 200 && response.status < 300) {
+        if (!response.arrayBuffer) {
+          throw new WokuError(
+            "The fetch implementation cannot read binary responses.",
+            { code: "config_error" }
+          );
+        }
+        return {
+          status: response.status,
+          body: new Uint8Array(await response.arrayBuffer()),
+          requestId: requestIdFrom(response.headers),
+          retryAfterSeconds: retryAfterFromHeaders(response.headers)
+        };
+      }
       const text = await response.text();
       return {
         status: response.status,
@@ -706,6 +736,14 @@ var NpsTools = class {
       }
     );
   }
+  /** Move the tool into a folder, or to the root with `folderId: null`. */
+  move(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/nps-tools/${encodeURIComponent(id)}/move`,
+      { ...opts, body }
+    );
+  }
   delete(id, opts) {
     return this.client.request(
       "delete",
@@ -745,6 +783,14 @@ var CsatTools = class {
       }
     );
   }
+  /** Move the tool into a folder, or to the root with `folderId: null`. */
+  move(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/csat-tools/${encodeURIComponent(id)}/move`,
+      { ...opts, body }
+    );
+  }
   delete(id, opts) {
     return this.client.request(
       "delete",
@@ -784,6 +830,14 @@ var CesTools = class {
       }
     );
   }
+  /** Move the tool into a folder, or to the root with `folderId: null`. */
+  move(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/ces-tools/${encodeURIComponent(id)}/move`,
+      { ...opts, body }
+    );
+  }
   delete(id, opts) {
     return this.client.request(
       "delete",
@@ -1001,9 +1055,11 @@ var Flows = class {
   constructor(client) {
     this.client = client;
   }
+  /** List the flows of the company, with their ordered `steps`. */
   list(params, opts) {
     return this.client.getPage("/v1/flows", params, opts);
   }
+  /** The data of a flow: ordered steps with their tools, wokus and branding. */
   get(id, opts) {
     return this.client.request(
       "get",
@@ -1011,6 +1067,33 @@ var Flows = class {
       opts
     );
   }
+  /**
+   * Create a flow from 1 to 20 ordered steps (each tool once, all of your
+   * company). Flows live outside folders.
+   */
+  create(body, opts) {
+    return this.client.request("post", "/v1/flows", {
+      ...opts,
+      body,
+      idempotent: true
+    });
+  }
+  /** Rename a flow or replace its full ordered list of steps. */
+  update(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/flows/${encodeURIComponent(id)}`,
+      { ...opts, body }
+    );
+  }
+  /** Delete a flow. Its tools and their responses stay. */
+  delete(id, opts) {
+    return this.client.request(
+      "delete",
+      `/v1/flows/${encodeURIComponent(id)}`,
+      opts
+    );
+  }
 };
 
 // src/resources/action-plans.ts
@@ -1508,6 +1591,240 @@ var Quarantines = class {
   }
 };
 
+// src/resources/folders.ts
+var Folders = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every folder of the company, or the direct subfolders of `parentFolderId`. */
+  list(params, opts) {
+    return this.client.request("get", "/v1/folders", {
+      ...opts,
+      query: { ...params, ...opts?.query }
+    });
+  }
+  get(id, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(id)}`,
+      opts
+    );
+  }
+  create(body, opts) {
+    return this.client.request("post", "/v1/folders", {
+      ...opts,
+      body,
+      idempotent: true
+    });
+  }
+  /**
+   * Rename or recolor a folder (`color: null` clears the color) and/or replace
+   * its WhatsApp alert recipients (`whatsappAlertRecipients`, `[]` clears them).
+   */
+  update(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/folders/${encodeURIComponent(id)}`,
+      { ...opts, body }
+    );
+  }
+  /**
+   * Move a folder under another folder, or to the root with
+   * `parentFolderId: null`. A folder cannot move into its own subtree.
+   */
+  move(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/folders/${encodeURIComponent(id)}/move`,
+      { ...opts, body }
+    );
+  }
+  /**
+   * Delete a folder. Nothing inside is deleted: subfolders, wokus and tools
+   * move up to the parent folder (or the root).
+   */
+  delete(id, opts) {
+    return this.client.request(
+      "delete",
+      `/v1/folders/${encodeURIComponent(id)}`,
+      opts
+    );
+  }
+  /**
+   * AI report over every woku, NPS, CSAT and CES tool of the folder and its
+   * subfolders. Scales differ per type, so there is no rating distribution.
+   */
+  report(id, params, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(id)}/report`,
+      { ...opts, query: { ...params, ...opts?.query } }
+    );
+  }
+  /**
+   * Per-tool figures of the woku, NPS, CSAT and CES tools of the folder and its
+   * subfolders for a period against the one before it, with the daily sums and
+   * the histogram of scores. `days` is 7, 30 (default) or 90, or 0 for the whole
+   * history (every `previous` window is then empty). The period is the last
+   * `days` calendar days in UTC, today included. Scales are never mixed across
+   * types.
+   */
+  metrics(id, params, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(id)}/metrics`,
+      { ...opts, query: { ...params, ...opts?.query } }
+    );
+  }
+  /** CSV text with one row per response of every tool of the folder subtree. */
+  csv(id, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(id)}/csv`,
+      opts
+    );
+  }
+  /**
+   * PDF of the folder report (every woku, NPS, CSAT and CES tool of the folder
+   * and its subfolders) with a breakdown per type on each native scale.
+   * Returns the file bytes: write them to disk or send them as is.
+   */
+  pdf(id, params, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(id)}/pdf`,
+      {
+        ...opts,
+        headers: { Accept: "application/pdf", ...opts?.headers },
+        query: { ...params, ...opts?.query },
+        binary: true
+      }
+    );
+  }
+};
+
+// src/resources/tools.ts
+var ToolsPage = class {
+  constructor(response, fetchNext, fetchMoreFolders = () => Promise.reject(new RangeError("No more folders"))) {
+    this.fetchNext = fetchNext;
+    this.fetchMoreFolders = fetchMoreFolders;
+    this.folders = response.folders;
+    this.tools = response.tools;
+    this.nextCursor = response.nextCursor;
+    this.foldersNextCursor = response.foldersNextCursor ?? null;
+    this.facets = response.facets;
+  }
+  hasMoreFolders() {
+    return this.foldersNextCursor !== null;
+  }
+  /** The next page of folders ("see more"): a page with those folders and no tools. */
+  getMoreFolders() {
+    if (this.foldersNextCursor === null)
+      throw new RangeError("No more folders");
+    return this.fetchMoreFolders(this.foldersNextCursor);
+  }
+  hasNextPage() {
+    return this.nextCursor !== null;
+  }
+  getNextPage() {
+    if (this.nextCursor === null) throw new RangeError("No next page");
+    return this.fetchNext(this.nextCursor);
+  }
+  async *iterPages() {
+    yield this;
+    if (this.hasNextPage()) yield* (await this.getNextPage()).iterPages();
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.iterPages()) {
+      for (const tool of page.tools) yield tool;
+    }
+  }
+};
+var Tools = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List one folder level (or search the company). Folders and tools of every
+   * type come together; the first page also carries the folders and facets.
+   */
+  async list(params, opts) {
+    const fetchPage = async (cursor, foldersCursor) => {
+      const response = await this.client.request(
+        "get",
+        "/v1/tools",
+        {
+          ...opts,
+          query: {
+            ...params,
+            types: params?.types?.join(","),
+            ...cursor ? { cursor } : {},
+            ...foldersCursor ? { foldersCursor } : {},
+            ...opts?.query
+          }
+        }
+      );
+      return new ToolsPage(
+        response,
+        fetchPage,
+        (next) => fetchPage(void 0, next)
+      );
+    };
+    return fetchPage();
+  }
+  /**
+   * Headline figures per type (woku stars, NPS score, CSAT satisfied %, CES
+   * mean) for the company or one folder and its subfolders, in a period.
+   * A type that fails reports `{ error: true }`; the others stay valid.
+   */
+  stats(params, opts) {
+    return this.client.request("get", "/v1/tools/stats", {
+      ...opts,
+      query: { ...params, ...opts?.query }
+    });
+  }
+  /**
+   * Move up to 200 items of mixed types (`woku`, `nps`, `csat`, `ces`,
+   * `folder`) into a folder, or to the root with `folderId: null`. Idempotent;
+   * nothing moves if one item or the destination is not found.
+   */
+  move(body, opts) {
+    return this.client.request("post", "/v1/tools/move", {
+      ...opts,
+      body
+    });
+  }
+};
+
+// src/resources/journey-folders.ts
+var JourneyFolders = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Whether the organization is on, running, and how much is still without a folder. */
+  status(opts) {
+    return this.client.request(
+      "get",
+      "/v1/journey-folders",
+      opts
+    );
+  }
+  /**
+   * Switch the organization on and run the one-off pass in the background: tools
+   * of existing journeys without a folder move into their moment folder, and
+   * tools journeys create from now on are placed there. Tools that already have
+   * a folder are never touched. Rejects with a conflict (409) while a pass is
+   * already running; poll {@link status} for progress.
+   */
+  organize(opts) {
+    return this.client.request(
+      "post",
+      "/v1/journey-folders/organize",
+      opts
+    );
+  }
+};
+
 // src/woku.ts
 var Woku = class {
   constructor(options) {
@@ -1527,11 +1844,15 @@ var Woku = class {
     this.actionPlans = new ActionPlans(this.client);
     this.actionPlanGroups = new ActionPlanGroups(this.client);
     this.tickets = new Tickets(this.client);
+    this.followUps = new FollowUps(this.client);
     this.ticketDestinations = new TicketDestinations(this.client);
     this.dispatches = new Dispatches(this.client);
     this.reports = new Reports(this.client);
     this.company = new Company(this.client);
     this.journeys = new Journeys(this.client);
+    this.folders = new Folders(this.client);
+    this.tools = new Tools(this.client);
+    this.journeyFolders = new JourneyFolders(this.client);
     this.quarantines = new Quarantines(this.client);
   }
 };
@@ -1539,7 +1860,10 @@ var Woku = class {
 exports.AuthenticationError = AuthenticationError;
 exports.BadRequestError = BadRequestError;
 exports.ConflictError = ConflictError;
+exports.Folders = Folders;
+exports.FollowUps = FollowUps;
 exports.InternalServerError = InternalServerError;
+exports.JourneyFolders = JourneyFolders;
 exports.Journeys = Journeys;
 exports.Media = Media;
 exports.NotFoundError = NotFoundError;
@@ -1547,6 +1871,8 @@ exports.Page = Page;
 exports.PayloadTooLargeError = PayloadTooLargeError;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
+exports.Tools = Tools;
+exports.ToolsPage = ToolsPage;
 exports.UnprocessableEntityError = UnprocessableEntityError;
 exports.Woku = Woku;
 exports.WokuAPIError = WokuAPIError;