@wokuapp/react-native 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @wokuapp/react-native
 
-Capture **Woku ratings** and **NPS** (text + audio) from your React Native
+Capture **Woku, NPS, CSAT and CES** from your React Native
 app, with offline buffering and quarantine-aware delivery.
 
 [![npm](https://img.shields.io/npm/v/@wokuapp/react-native)](https://www.npmjs.com/package/@wokuapp/react-native)
@@ -18,18 +18,24 @@ your own ingestion, retry, or offline logic. The SDK:
 
 - Captures **Woku ratings** (1–5) and **NPS** (0–10) with optional text or
   audio comments.
-- **Buffers offline** and retries automatically when connectivity returns —
-  a tap on the subway never loses a response.
+- **Buffers offline** through your storage adapter. Call `flush()` when
+  connectivity returns; the headless core has no connectivity listener.
 - Is **quarantine-aware**: when the backend rate-limits a respondent (HTTP
   429), the SDK backs off instead of hammering it.
 - Has **zero runtime dependencies** and a **fully typed**, framework-agnostic
   core: you inject the platform adapters (storage, http, audio), so it stays
   small and testable.
 
-> **Architecture note (v0.1).** This release ships the headless TypeScript
+> **Architecture note.** This release ships the headless TypeScript
 > core plus the adapter interfaces. Pre-built React Native adapters
 > (MMKV storage, audio recorder) ship in a follow-up minor; until then you
 > wire your app's libraries to the small interfaces below (a few lines).
+> Captures post to the resource-oriented `/v1/captures` endpoint and are
+> tagged server-side with the `mobile-sdk` response channel. Text/rating and
+> score captures are sent as JSON; **audio captures are sent as multipart**
+> (the `audio.uri` file plus a `payload` field) and become a voicemail review
+> server-side. Submissions deduplicate by their client-generated `id` for 24h.
+> Older uncertain submissions are retained for inspection instead of replayed.
 
 ## Install
 
@@ -48,7 +54,7 @@ adapters land).
 import { WokuSdk } from '@wokuapp/react-native';
 
 const woku = new WokuSdk({
-  apiUrl: 'https://api.woku.app',
+  apiUrl: 'https://clientapi.woku.app',
   publicKey: 'pk_live_xxx', // per-company SDK key
   companyId: 'company_123',
   storage: mmkvStorageAdapter, // see "Adapters" below
@@ -61,11 +67,11 @@ await woku.captureNps({
   comment: 'Fast checkout, loved it.',
 });
 
-// Woku rating (1–5) with an audio comment
+// Woku rating (1–5) with a text comment
 await woku.captureWoku({
   wokuId: 'woku_store_centro',
   rating: 5,
-  audio: { uri: fileUri, mimeType: 'audio/m4a', durationMs: 4200 },
+  comment: 'Great staff, quick service.',
   respondent: { email: 'ana@example.com' },
 });
 
@@ -110,12 +116,12 @@ const http: HttpClient = { request: async (req) => /* ... */ };
 
 `flush()` walks the queue oldest-first:
 
-| Outcome            | Behavior                                                                                               |
-| ------------------ | ------------------------------------------------------------------------------------------------------ |
-| `sent`             | removed from the queue                                                                                 |
-| quarantine (429)   | **stops** the flush, keeps everything for the next attempt                                             |
-| network error      | attempt count bumped, item kept, flush continues                                                       |
-| `failed` (4xx/5xx) | attempt count bumped; dropped after `maxQueueAttempts` (default 8) so a bad item can't wedge the queue |
+| Outcome            | Behavior                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `sent`             | removed from the queue                                                                 |
+| quarantine (429)   | **stops** the flush, keeps everything for the next attempt                             |
+| network error      | attempt count bumped, item kept, flush continues                                       |
+| `failed` (4xx/5xx) | permanent 4xx retained as failed; transient errors retained after the 8-attempt budget |
 
 The queue persists through your `Storage` adapter, so it survives restarts.
 
@@ -125,10 +131,13 @@ The queue persists through your `Storage` adapter, so it survives restarts.
 | --------------------- | --------------------------------------------------- |
 | `new WokuSdk(config)` | Create an SDK instance.                             |
 | `captureWoku(input)`  | Submit a 1–5 rating (+ comment/audio).              |
+| `captureCsat(input)`  | Submit a 1–5 satisfaction score.                    |
+| `captureCes(input)`   | Submit a 1–5 effort score.                          |
+| `failedCaptures()`    | Inspect retained failures and their reason.         |
 | `captureNps(input)`   | Submit a 0–10 NPS score (+ review).                 |
 | `flush()`             | Retry all queued captures. Returns a `FlushResult`. |
 | `pendingCount()`      | Number of captures waiting to send.                 |
-| `clearQueue()`        | Drop the queue (e.g. on logout).                    |
+| `clearQueue()`        | Remove only this company's pending and failed rows. |
 
 Lower-level building blocks `WokuClient` and `OfflineQueue` are exported too,
 along with all types and error classes (`WokuValidationError`,
@@ -137,3 +146,53 @@ along with all types and error classes (`WokuValidationError`,
 ## License
 
 [MIT](../../LICENSE) © Woku
+
+## Identified journey responses
+
+```ts
+await sdk.captureCsat({
+  csatId: prepared.toolId,
+  score: 5,
+  respondent: { email: customer.email },
+  dispatchToken: prepared.token,
+});
+await sdk.captureCes({
+  cesId: effortToolId,
+  score: 4,
+  respondent: { phone: customer.phone },
+});
+```
+
+Use only a public pk\_ key: the transport uses x-woku-key and rejects management
+keys. remoteId is the server id. Woku/NPS audio supports language es/en (default
+Spanish); CSAT/CES audio is not supported. timeoutMs bounds an attempt (default
+30s), including injected adapters.
+
+Await capture calls and provide persistent storage. Captures are stored before
+delivery. Call flush on reconnect/foreground; the core has no connectivity listener.
+Company-scoped instances never send or clear another company's rows. Concurrent
+enqueue/flush preserves incoming data. Share one storage adapter per app and one
+SDK per company; isolate storage between API environments.
+
+Inspect failedCaptures for permanent failures, exhausted attempts and captures
+older than the server's 24-hour replay window (based on the device clock). These records are retained and are
+not blindly sent with a new id: inspect delivery before resubmitting. clearQueue
+removes only the current company's pending and retained failed rows.
+
+The published package includes separate ESM/CJS JavaScript and matching
+`.d.ts`/`.d.cts` exports. Both imports are checked against the packed artifact.
+
+### Delivery failures and clearing
+
+`timeoutMs` covers receiving the response and reading its body. Validation
+messages use the API's nested error envelope and remain strings. If the server
+confirms a capture but local acknowledgement cannot be stored, the capture call
+still returns `sent`; the pending row retains its original ID for a safe later
+flush. A storage failure before enqueue prevents the network request.
+
+`clearQueue()` removes this company's rows and prevents an active flush from
+starting further sends from its old snapshot. An already started request may
+finish and cannot be recalled.
+
+Persisted capture queues reject malformed rows with `WokuConfigError` and preserve
+the stored bytes for recovery instead of overwriting them.

package/dist/index.cjs

@@ -6,7 +6,8 @@ var fetchHttpClient = {
     const res = await fetch(req.url, {
       method: req.method,
       headers: req.headers,
-      body: req.body
+      body: req.body,
+      signal: req.signal
     });
     return {
       status: res.status,
@@ -71,12 +72,16 @@ var WokuNetworkError = class extends WokuError {
 };
 
 // src/client.ts
-var DEFAULT_CAPTURE_PATH = "/sdk/v1/captures";
+var DEFAULT_CAPTURE_PATH = "/v1/captures";
 var WokuClient = class {
   constructor(config) {
     this.config = config;
     if (!config.apiUrl) throw new WokuConfigError("apiUrl is required");
     if (!config.publicKey) throw new WokuConfigError("publicKey is required");
+    if (config.publicKey.startsWith("sk_"))
+      throw new WokuConfigError(
+        "Use a publishable key, never a management secret key, in a mobile app."
+      );
     if (!config.companyId) throw new WokuConfigError("companyId is required");
     this.http = config.http ?? fetchHttpClient;
     this.logger = config.logger ?? noopLogger;
@@ -91,37 +96,87 @@ var WokuClient = class {
    * non-2xx responses (so the caller can decide to re-queue).
    */
   async send(submission) {
-    let response;
-    try {
-      response = await this.http.request({
-        method: "POST",
-        url: this.endpoint,
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.publicKey}`,
-          "X-Woku-Company": this.config.companyId,
-          "X-Woku-Idempotency-Key": submission.id
-        },
-        body: JSON.stringify(submission)
+    if (submission.companyId !== this.config.companyId)
+      throw new WokuConfigError(
+        "Cannot deliver a capture for another company."
+      );
+    if (submission.audio && !submission.language)
+      submission = { ...submission, language: this.config.language ?? "es" };
+    const headers = {
+      "x-woku-key": this.config.publicKey,
+      "X-Woku-Company": this.config.companyId,
+      "X-Woku-Idempotency-Key": submission.id
+    };
+    let requestBody;
+    if (submission.audio) {
+      const form = new FormData();
+      form.append("file", {
+        uri: submission.audio.uri,
+        type: submission.audio.mimeType,
+        name: "capture-audio"
       });
-    } catch (err) {
-      throw new WokuNetworkError(err.message);
+      form.append("payload", JSON.stringify(submission));
+      requestBody = form;
+    } else {
+      headers["Content-Type"] = "application/json";
+      requestBody = JSON.stringify(submission);
     }
-    if (response.ok) {
-      const body2 = await this.safeJson(response.json);
-      return { id: submission.id, status: "sent", remoteId: body2?.id };
-    }
-    if (response.status === 429) {
-      const retryAfter = Number(response.headers.get("Retry-After"));
-      throw new WokuQuarantineError(
-        "Submission blocked by quarantine",
-        Number.isFinite(retryAfter) ? retryAfter : void 0
+    const controller = new AbortController();
+    let timer;
+    try {
+      return await Promise.race([
+        (async () => {
+          const response = await this.http.request({
+            method: "POST",
+            url: this.endpoint,
+            headers,
+            body: requestBody,
+            signal: controller.signal
+          });
+          if (response.ok) {
+            const body2 = await this.safeJson(response.json);
+            return {
+              id: submission.id,
+              status: "sent",
+              remoteId: body2?.remoteId ?? body2?.id
+            };
+          }
+          if (response.status === 429) {
+            const raw = response.headers.get("Retry-After");
+            const retryAfter = raw === null ? void 0 : Number(raw);
+            throw new WokuQuarantineError(
+              "Submission blocked by quarantine",
+              retryAfter !== void 0 && Number.isFinite(retryAfter) ? Math.max(0, retryAfter) : void 0
+            );
+          }
+          const body = await this.safeJson(response.json);
+          const value = body?.message;
+          const message = value && typeof value === "object" && !Array.isArray(value) ? value.message : value;
+          const detail = Array.isArray(message) ? message.filter((item) => typeof item === "string").join(", ") : message;
+          const error = typeof detail === "string" && detail ? detail : `HTTP ${response.status}`;
+          this.logger.warn(`woku capture rejected: ${error}`);
+          return {
+            id: submission.id,
+            status: "failed",
+            error,
+            retryable: response.status === 408 || response.status >= 500
+          };
+        })(),
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => {
+            controller.abort();
+            reject(new WokuNetworkError("Capture request timed out"));
+          }, this.config.timeoutMs ?? 3e4);
+        })
+      ]);
+    } catch (err) {
+      if (err instanceof WokuQuarantineError) throw err;
+      throw new WokuNetworkError(
+        err instanceof Error ? err.message : "Capture request failed"
       );
+    } finally {
+      if (timer) clearTimeout(timer);
     }
-    const body = await this.safeJson(response.json);
-    const error = body?.message ?? `HTTP ${response.status}`;
-    this.logger.warn(`woku capture rejected: ${error}`);
-    return { id: submission.id, status: "failed", error };
   }
   async safeJson(json) {
     try {
@@ -134,94 +189,193 @@ var WokuClient = class {
 
 // src/queue.ts
 var DEFAULT_KEY = "woku.sdk.queue.v1";
-var DEFAULT_MAX_ATTEMPTS = 8;
+var mutations = /* @__PURE__ */ new WeakMap();
+var flushes = /* @__PURE__ */ new WeakMap();
 var OfflineQueue = class {
   constructor(opts = {}) {
-    this.items = null;
     this.storage = opts.storage ?? new InMemoryStorage();
     this.key = opts.storageKey ?? DEFAULT_KEY;
-    this.maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    this.maxAttempts = opts.maxAttempts ?? 8;
+    this.companyId = opts.companyId;
+  }
+  owned(item) {
+    return !this.companyId || item.submission.companyId === this.companyId;
   }
   async load() {
-    if (this.items) return this.items;
     const raw = await this.storage.getItem(this.key);
-    if (!raw) {
-      this.items = [];
-      return this.items;
-    }
+    if (!raw) return [];
     try {
       const parsed = JSON.parse(raw);
-      this.items = Array.isArray(parsed) ? parsed : [];
+      if (Array.isArray(parsed) && parsed.every(
+        (item) => item && typeof item === "object" && item.submission && typeof item.submission.id === "string" && typeof item.submission.companyId === "string" && Number.isFinite(item.submission.createdAt) && Number.isInteger(item.attempts) && item.attempts >= 0
+      ))
+        return parsed;
     } catch {
-      this.items = [];
     }
-    return this.items;
+    throw new WokuConfigError(
+      "The capture queue contains invalid data; repair it before writing."
+    );
   }
-  async persist() {
-    await this.storage.setItem(this.key, JSON.stringify(this.items ?? []));
+  async persist(items) {
+    await this.storage.setItem(this.key, JSON.stringify(items));
+  }
+  mutation(run) {
+    let locks = mutations.get(this.storage);
+    if (!locks) {
+      locks = /* @__PURE__ */ new Map();
+      mutations.set(this.storage, locks);
+    }
+    const previous = locks.get(this.key) ?? Promise.resolve();
+    const result = previous.then(run, run);
+    const settled = result.then(
+      () => void 0,
+      () => void 0
+    );
+    locks.set(this.key, settled);
+    void settled.then(() => {
+      if (locks?.get(this.key) === settled) locks.delete(this.key);
+    });
+    return result;
   }
-  /** Adds a submission to the tail of the queue (dedup by id). */
   async enqueue(submission) {
-    const items = await this.load();
-    if (items.some((i) => i.submission.id === submission.id)) return;
-    items.push({ submission, attempts: 0 });
-    await this.persist();
+    if (this.companyId && submission.companyId !== this.companyId)
+      throw new WokuConfigError(
+        "Cannot enqueue a capture from another company."
+      );
+    const snapshot = JSON.parse(
+      JSON.stringify(submission)
+    );
+    return this.mutation(async () => {
+      const items = await this.load();
+      if (items.some(
+        (item) => item.submission.id === snapshot.id && item.submission.companyId === snapshot.companyId
+      ))
+        return;
+      items.push({ submission: snapshot, attempts: 0 });
+      await this.persist(items);
+    });
   }
-  async size() {
-    return (await this.load()).length;
+  size() {
+    return this.mutation(
+      async () => (await this.load()).filter((item) => this.owned(item) && !item.failure).length
+    );
   }
-  /** Returns a copy of the pending submissions (oldest first). */
-  async pending() {
-    return (await this.load()).map((i) => i.submission);
+  pending() {
+    return this.mutation(
+      async () => (await this.load()).filter((item) => this.owned(item) && !item.failure).map((item) => item.submission)
+    );
   }
-  /**
-   * Attempts to deliver every queued submission through `send`, applying
-   * the delivery semantics documented on the class. Persists once at the
-   * end and returns a summary.
-   */
-  async flush(send) {
-    const items = await this.load();
-    const survivors = [];
-    let sent = 0;
-    let failed = 0;
-    let quarantined = false;
-    for (let index = 0; index < items.length; index++) {
-      const item = items[index];
-      if (quarantined) {
-        survivors.push(item);
+  failures() {
+    return this.mutation(
+      async () => (await this.load()).filter((item) => this.owned(item) && item.failure).map((item) => ({
+        submission: item.submission,
+        reason: item.failure
+      }))
+    );
+  }
+  acknowledge(submission) {
+    return this.mutation(async () => {
+      const items = await this.load();
+      await this.persist(
+        items.filter(
+          (item) => !(item.submission.id === submission.id && item.submission.companyId === submission.companyId && this.owned(item))
+        )
+      );
+    });
+  }
+  reject(submission, reason) {
+    return this.mutation(async () => {
+      const items = await this.load();
+      const item = items.find(
+        (row) => row.submission.id === submission.id && row.submission.companyId === submission.companyId && this.owned(row)
+      );
+      if (item) {
+        item.failure = reason;
+        await this.persist(items);
+      }
+    });
+  }
+  flush(send) {
+    let jobs = flushes.get(this.storage);
+    if (!jobs) {
+      jobs = /* @__PURE__ */ new Map();
+      flushes.set(this.storage, jobs);
+    }
+    const scope = JSON.stringify([this.key, this.companyId ?? "*"]);
+    const existing = jobs.get(scope);
+    if (existing) return existing;
+    const result = this.runFlush(send).finally(() => {
+      if (jobs?.get(scope) === result) jobs.delete(scope);
+    });
+    jobs.set(scope, result);
+    return result;
+  }
+  async runFlush(send) {
+    const batch = await this.pending();
+    let sent = 0, failed = 0, quarantined = false;
+    for (const candidate of batch) {
+      const current = await this.mutation(
+        async () => (await this.load()).find(
+          (item) => this.owned(item) && !item.failure && item.submission.id === candidate.id && item.submission.companyId === candidate.companyId
+        )
+      );
+      if (!current) continue;
+      const submission = current.submission;
+      if (submission.createdAt > 0 && Date.now() - submission.createdAt >= 24 * 60 * 60 * 1e3) {
+        await this.reject(
+          submission,
+          "Retry window expired; inspect delivery before resubmitting."
+        );
+        failed++;
         continue;
       }
+      let permanent = false;
+      let reason;
+      let accepted = false;
       try {
-        const result = await send(item.submission);
-        if (result.status === "sent") {
-          sent++;
-        } else {
-          item.attempts++;
-          if (item.attempts >= this.maxAttempts) failed++;
-          else survivors.push(item);
-        }
-      } catch (err) {
-        if (err instanceof WokuQuarantineError) {
+        const result = await send(submission);
+        accepted = result.status === "sent";
+        reason = result.error;
+        permanent = result.retryable === false;
+      } catch (error) {
+        if (error instanceof WokuQuarantineError) {
           quarantined = true;
-          survivors.push(item);
-        } else if (err instanceof WokuNetworkError) {
-          item.attempts++;
-          survivors.push(item);
-        } else {
-          item.attempts++;
-          if (item.attempts >= this.maxAttempts) failed++;
-          else survivors.push(item);
+          break;
         }
+        reason = error instanceof Error ? error.message : "Delivery failed";
       }
+      const outcome = await this.mutation(async () => {
+        const items = await this.load();
+        const index = items.findIndex(
+          (item) => item.submission.id === submission.id && item.submission.companyId === submission.companyId && !item.failure
+        );
+        if (index < 0) return "removed";
+        if (accepted) items.splice(index, 1);
+        else {
+          const item = items[index];
+          item.attempts++;
+          if (permanent || item.attempts >= this.maxAttempts)
+            item.failure = reason ?? "Attempt budget exhausted";
+        }
+        const exhausted = !accepted && Boolean(items[index]?.failure);
+        await this.persist(items);
+        return accepted ? "sent" : exhausted ? "failed" : "pending";
+      });
+      if (outcome === "sent") sent++;
+      if (outcome === "failed") failed++;
     }
-    this.items = survivors;
-    await this.persist();
-    return { sent, failed, remaining: survivors.length, quarantined };
+    return { sent, failed, remaining: await this.size(), quarantined };
   }
-  /** Clears the queue (e.g. on logout). */
-  async clear() {
-    this.items = [];
-    await this.storage.removeItem(this.key);
+  clear() {
+    return this.mutation(async () => {
+      if (!this.companyId) {
+        await this.storage.removeItem(this.key);
+        return;
+      }
+      const remaining = (await this.load()).filter((item) => !this.owned(item));
+      if (remaining.length) await this.persist(remaining);
+      else await this.storage.removeItem(this.key);
+    });
   }
 };
 
@@ -243,10 +397,12 @@ var WokuSdk = class {
     this.client = new WokuClient(config);
     this.queue = new OfflineQueue({
       storage: config.storage,
+      companyId: config.companyId,
       maxAttempts: config.maxQueueAttempts
     });
     this.logger = config.logger ?? noopLogger;
     this.companyId = config.companyId;
+    this.language = config.language ?? "es";
   }
   /** Captures a Woku rating (1..5) with optional text/audio comment. */
   async captureWoku(input) {
@@ -261,6 +417,8 @@ var WokuSdk = class {
       audio: input.audio,
       respondent: input.respondent,
       metadata: input.metadata,
+      dispatchToken: input.dispatchToken,
+      language: input.language ?? (input.audio ? this.language : void 0),
       createdAt: Date.now()
     };
     return this.deliver(submission);
@@ -278,10 +436,42 @@ var WokuSdk = class {
       audio: input.audio,
       respondent: input.respondent,
       metadata: input.metadata,
+      dispatchToken: input.dispatchToken,
+      language: input.language ?? (input.audio ? this.language : void 0),
       createdAt: Date.now()
     };
     return this.deliver(submission);
   }
+  async captureCsat(input) {
+    assertInt(input.score, 1, 5, "score");
+    return this.deliver({
+      id: generateId(),
+      kind: "csat",
+      companyId: this.companyId,
+      targetId: input.csatId,
+      score: input.score,
+      comment: input.comment,
+      respondent: input.respondent,
+      metadata: input.metadata,
+      dispatchToken: input.dispatchToken,
+      createdAt: Date.now()
+    });
+  }
+  async captureCes(input) {
+    assertInt(input.score, 1, 5, "score");
+    return this.deliver({
+      id: generateId(),
+      kind: "ces",
+      companyId: this.companyId,
+      targetId: input.cesId,
+      score: input.score,
+      comment: input.comment,
+      respondent: input.respondent,
+      metadata: input.metadata,
+      dispatchToken: input.dispatchToken,
+      createdAt: Date.now()
+    });
+  }
   /** Retries every queued submission. Safe to call on app foreground or
    *  when connectivity is regained. */
   flush() {
@@ -291,6 +481,10 @@ var WokuSdk = class {
   pendingCount() {
     return this.queue.size();
   }
+  /** Inspect retained captures whose automatic attempt budget was exhausted. */
+  failedCaptures() {
+    return this.queue.failures();
+  }
   /** Clears the offline queue (e.g. on user logout). */
   clearQueue() {
     return this.queue.clear();
@@ -300,9 +494,25 @@ var WokuSdk = class {
    * submission is queued for a later flush rather than thrown away.
    */
   async deliver(submission) {
+    submission = JSON.parse(JSON.stringify(submission));
+    await this.queue.enqueue(submission);
     try {
       const result = await this.client.send(submission);
-      if (result.status === "sent") return result;
+      if (result.status === "sent") {
+        try {
+          await this.queue.acknowledge(submission);
+        } catch {
+          this.logger.warn(
+            "Capture accepted; local acknowledgement is pending",
+            { id: submission.id }
+          );
+        }
+        return result;
+      }
+      if (result.retryable === false) {
+        await this.queue.reject(submission, result.error ?? "Capture rejected");
+        return result;
+      }
       await this.queue.enqueue(submission);
       return { ...result, status: "queued" };
     } catch (err) {