@wokuapp/sdk 0.3.0 → 0.4.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

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.4.0";
 
 // src/core/errors.ts
 var WokuError = class extends Error {
@@ -1527,6 +1542,7 @@ 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);
@@ -1539,6 +1555,7 @@ var Woku = class {
 exports.AuthenticationError = AuthenticationError;
 exports.BadRequestError = BadRequestError;
 exports.ConflictError = ConflictError;
+exports.FollowUps = FollowUps;
 exports.InternalServerError = InternalServerError;
 exports.Journeys = Journeys;
 exports.Media = Media;