@wokuapp/sdk 0.4.0 → 0.6.0

package/README.md

@@ -313,9 +313,132 @@ 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 });
+// Or a custom range of UTC days (both inclusive), as the admin custom period.
+const september = await woku.folders.metrics(folder.id, {
+  from: '2026-09-01',
+  to: '2026-09-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' })) {
@@ -375,8 +498,8 @@ 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`.
+`ticketDestinations`, `dispatches`, `reports`, `company`, `journeys`,
+`folders`, `tools`, `journeyFolders`.
 
 ## License
 

package/dist/index.cjs

@@ -38,7 +38,7 @@ var FollowUps = class {
 };
 
 // package.json
-var version = "0.4.0";
+var version = "0.6.0";
 
 // src/core/errors.ts
 var WokuError = class extends Error {
@@ -385,7 +385,8 @@ var WokuClient = class {
           headers,
           bodyText,
           timeout,
-          args.signal
+          args.signal,
+          args.binary
         );
         if (status >= 200 && status < 300) {
           return body;
@@ -502,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();
@@ -523,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,
@@ -721,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",
@@ -760,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",
@@ -799,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",
@@ -1016,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",
@@ -1026,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
@@ -1509,18 +1577,239 @@ var Journeys = class {
   }
 };
 
-// src/resources/quarantines.ts
-var Quarantines = class {
+// src/resources/folders.ts
+var Folders = class {
   constructor(client) {
     this.client = client;
   }
-  /** Check whether a contact is quarantined. */
-  check(params, opts) {
-    return this.client.request("get", "/v1/quarantines/check", {
+  /** 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. Or a custom range with `from`
+   * and `to` (`YYYY-MM-DD` UTC days, both inclusive, up to 731 days), which
+   * replaces `days`. 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
@@ -1548,15 +1837,19 @@ var Woku = class {
     this.reports = new Reports(this.client);
     this.company = new Company(this.client);
     this.journeys = new Journeys(this.client);
-    this.quarantines = new Quarantines(this.client);
+    this.folders = new Folders(this.client);
+    this.tools = new Tools(this.client);
+    this.journeyFolders = new JourneyFolders(this.client);
   }
 };
 
 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;
@@ -1564,6 +1857,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;