@wokuapp/sdk 0.6.0 → 0.8.0

package/README.md

@@ -363,6 +363,8 @@ 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' });
+// Tools with the most recent responses first (tools without any go last).
+const recent = await woku.tools.list({ sort: '-lastResponse' });
 // Tracker chips (`name:value`): a tool matches when it has every one. Company-wide.
 const tagged = await woku.tools.list({ trackers: ['TRR:00482'] });
 
@@ -390,6 +392,11 @@ 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);
+// Only the responses of a period (`from` inclusive, `to` exclusive).
+const septemberCsv = await woku.folders.csv(folder.id, {
+  from: '2026-09-01T00:00:00.000Z',
+  to: '2026-10-01T00:00:00.000Z',
+});
 // 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' });
 
@@ -411,9 +418,13 @@ for (const tool of metrics.tools) {
 }
 
 // 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.
+// improvement (wokus, NPS, CSAT and CES). `allReviews: true` alerts every
+// review, recognitions too. The list replaces the previous one.
 await woku.folders.update(folder.id, {
-  whatsappAlertRecipients: [{ whatsappId: '56912345678', name: 'Ana' }],
+  whatsappAlertRecipients: [
+    { whatsappId: '56912345678', name: 'Ana' },
+    { whatsappId: '56987654321', name: 'Luis', allReviews: true },
+  ],
 });
 
 // Deleting a folder never deletes its content: it moves up to the parent.
@@ -436,6 +447,86 @@ Folders created by woku (journeys, moments, integrations) report their `origin`
 tools (`npsTools`, `csatTools`, `cesTools`) accept `folderId` on `create`, expose
 `folderId` on every tool and have `move(id, { folderId })`.
 
+NPS, CSAT and CES tools also take two response settings on `create` and
+`update`: `anonymousDisabled` (only identified answers) and
+`onlyOneResponsePerClient` (each identified client answers once; a repeat
+answer is rejected with HTTP 409 and the code `ALREADY_RESPONDED`). Both come
+back on every tool and can change even after the tool has responses, while its
+copy stays frozen:
+
+```ts
+await woku.npsTools.update('nps_tool_id', { onlyOneResponsePerClient: true });
+```
+
+### Scheduled reports
+
+Email the PDF report of a folder (every tool of its subtree, optionally with
+the CSV) or of one tool to up to 10 people, also outside woku. `monthly` goes
+out on the 1st, `biweekly` on the 1st and 16th and `weekly` on Mondays, at
+12:00 UTC with the previous complete period; `once` goes out at `sendAt` with
+its own period. Each email goes as the company with a one-click unsubscribe.
+
+```ts
+const monthly = await woku.reportSubscriptions.create({
+  scopeType: 'folder',
+  scopeId: folder.id,
+  frequency: 'monthly',
+  recipients: ['board@acme.com'],
+  includeCsv: true,
+});
+console.log(monthly.nextRunAt);
+
+// One report of a chosen period, sent right away.
+const once = await woku.reportSubscriptions.create({
+  scopeType: 'nps',
+  scopeId: 'nps_tool_id',
+  frequency: 'once',
+  recipients: ['ana@acme.com'],
+  periodFrom: '2026-09-01T00:00:00.000Z',
+  periodTo: '2026-10-01T00:00:00.000Z',
+});
+await woku.reportSubscriptions.send(once.id); // { status: 'sent', sent: 1 }
+
+await woku.reportSubscriptions.update(monthly.id, { active: false }); // pause
+const all = await woku.reportSubscriptions.list({
+  scopeType: 'folder',
+  scopeId: folder.id,
+});
+await woku.reportSubscriptions.delete(monthly.id);
+```
+
+### Folder participants
+
+Keep the list of people expected to answer the tools of a folder (a program's
+enrolled, for example) and see, per tool, who answered, who is missing and who
+answered more than once. One person per line: a name, an email and/or a phone
+with its country code; a CSV goes as is. Only identified responses can be
+matched, so each tool says whether it takes anonymous ones.
+
+```ts
+await woku.folderParticipants.replace(
+  folder.id,
+  'Ana, ana@acme.com\nLuis, +56 9 8765 4321',
+);
+await woku.folderParticipants.add(folder.id, 'carla@acme.com'); // skips people already listed
+
+const { participants, tools } = await woku.folderParticipants.get(folder.id);
+for (const tool of tools) {
+  const missing = tool.missing.map((i) => participants[i].name);
+  console.log(tool.name, tool.responded.length, missing, tool.anonymousAllowed);
+}
+
+// Send a tool again to the people who have not answered it.
+await woku.folderParticipants.resendToMissing(folder.id, {
+  toolType: 'nps',
+  toolId: 'nps_tool_id',
+  channel: 'email',
+}); // { missing, sent, withoutContact, failed }
+
+await woku.folderParticipants.remove(folder.id, participants[0].id);
+await woku.folderParticipants.clear(folder.id);
+```
+
 ## Pagination
 
 Paginated resource methods return a `Page` (journey enrollments and `tools.list` use a cursor envelope). Iterate every item across pages, or walk pages:
@@ -499,7 +590,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`, `journeys`,
-`folders`, `tools`, `journeyFolders`.
+`folders`, `folderParticipants`, `tools`, `journeyFolders`,
+`reportSubscriptions`.
 
 ## License
 

package/dist/index.cjs

@@ -38,7 +38,7 @@ var FollowUps = class {
 };
 
 // package.json
-var version = "0.6.0";
+var version = "0.8.0";
 
 // src/core/errors.ts
 var WokuError = class extends Error {
@@ -1663,12 +1663,15 @@ var Folders = class {
       { ...opts, query: { ...params, ...opts?.query } }
     );
   }
-  /** CSV text with one row per response of every tool of the folder subtree. */
-  csv(id, opts) {
+  /**
+   * CSV text with one row per response of every tool of the folder subtree,
+   * or only those of a period (`from` inclusive, `to` exclusive, ISO 8601).
+   */
+  csv(id, params, opts) {
     return this.client.request(
       "get",
       `/v1/folders/${encodeURIComponent(id)}/csv`,
-      opts
+      { ...opts, query: { ...params, ...opts?.query } }
     );
   }
   /**
@@ -1812,6 +1815,109 @@ var JourneyFolders = class {
   }
 };
 
+// src/resources/report-subscriptions.ts
+var ReportSubscriptions = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every scheduled report, or those of one folder or tool. */
+  list(params, opts) {
+    return this.client.request(
+      "get",
+      "/v1/report-subscriptions",
+      { ...opts, query: { ...params, ...opts?.query } }
+    );
+  }
+  create(body, opts) {
+    return this.client.request(
+      "post",
+      "/v1/report-subscriptions",
+      { ...opts, body }
+    );
+  }
+  /** Edit, pause or resume a recurring scheduled report. */
+  update(id, body, opts) {
+    return this.client.request(
+      "patch",
+      `/v1/report-subscriptions/${encodeURIComponent(id)}`,
+      { ...opts, body }
+    );
+  }
+  delete(id, opts) {
+    return this.client.request(
+      "delete",
+      `/v1/report-subscriptions/${encodeURIComponent(id)}`,
+      opts
+    );
+  }
+  /**
+   * Send it now: the last complete period of a recurring report (its
+   * schedule stays) or the period of a one-off (which then closes).
+   */
+  send(id, opts) {
+    return this.client.request(
+      "post",
+      `/v1/report-subscriptions/${encodeURIComponent(id)}/send`,
+      opts
+    );
+  }
+};
+
+// src/resources/folder-participants.ts
+var FolderParticipants = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** The list and, per tool of the folder subtree, who answered. */
+  get(folderId, opts) {
+    return this.client.request(
+      "get",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants`,
+      opts
+    );
+  }
+  /** Replace the whole list. */
+  replace(folderId, text, opts) {
+    return this.client.request(
+      "put",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants`,
+      { ...opts, body: { text } }
+    );
+  }
+  /** Add people; the ones already on the list are skipped. */
+  add(folderId, text, opts) {
+    return this.client.request(
+      "post",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants`,
+      { ...opts, body: { text } }
+    );
+  }
+  /** Remove one person (the `id` from `get`). */
+  remove(folderId, participantId, opts) {
+    return this.client.request(
+      "delete",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants/${encodeURIComponent(participantId)}`,
+      opts
+    );
+  }
+  /** Delete the whole list. Responses are never touched. */
+  clear(folderId, opts) {
+    return this.client.request(
+      "delete",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants`,
+      opts
+    );
+  }
+  /** Send a tool again to the people of the list who have not answered it. */
+  resendToMissing(folderId, body, opts) {
+    return this.client.request(
+      "post",
+      `/v1/folders/${encodeURIComponent(folderId)}/participants/resend`,
+      { ...opts, body }
+    );
+  }
+};
+
 // src/woku.ts
 var Woku = class {
   constructor(options) {
@@ -1838,6 +1944,8 @@ var Woku = class {
     this.company = new Company(this.client);
     this.journeys = new Journeys(this.client);
     this.folders = new Folders(this.client);
+    this.folderParticipants = new FolderParticipants(this.client);
+    this.reportSubscriptions = new ReportSubscriptions(this.client);
     this.tools = new Tools(this.client);
     this.journeyFolders = new JourneyFolders(this.client);
   }
@@ -1846,6 +1954,7 @@ var Woku = class {
 exports.AuthenticationError = AuthenticationError;
 exports.BadRequestError = BadRequestError;
 exports.ConflictError = ConflictError;
+exports.FolderParticipants = FolderParticipants;
 exports.Folders = Folders;
 exports.FollowUps = FollowUps;
 exports.InternalServerError = InternalServerError;
@@ -1857,6 +1966,7 @@ exports.Page = Page;
 exports.PayloadTooLargeError = PayloadTooLargeError;
 exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
+exports.ReportSubscriptions = ReportSubscriptions;
 exports.Tools = Tools;
 exports.ToolsPage = ToolsPage;
 exports.UnprocessableEntityError = UnprocessableEntityError;