@wokuapp/react-native 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,279 @@
+/**
+ * Injectable adapters. The SDK core never imports React Native or a
+ * concrete HTTP/storage library directly — host apps provide these so
+ * the core stays unit-testable and platform-agnostic.
+ */
+/** Minimal HTTP response the SDK needs. */
+interface HttpResponse {
+    status: number;
+    ok: boolean;
+    json: () => Promise<unknown>;
+    headers: {
+        get: (name: string) => string | null;
+    };
+}
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/** HTTP transport. Defaults to global `fetch`. */
+interface HttpClient {
+    request: (req: HttpRequest) => Promise<HttpResponse>;
+}
+/**
+ * Key/value persistence for the offline queue. React Native apps pass an
+ * MMKV or AsyncStorage-backed adapter; tests use the in-memory one.
+ */
+interface Storage {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+}
+interface Logger {
+    debug: (msg: string, meta?: unknown) => void;
+    warn: (msg: string, meta?: unknown) => void;
+    error: (msg: string, meta?: unknown) => void;
+}
+/** Default HTTP client backed by the global `fetch`. */
+declare const fetchHttpClient: HttpClient;
+/** In-memory storage. Default for tests and ephemeral usage. */
+declare class InMemoryStorage implements Storage {
+    private readonly map;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** No-op logger (default). */
+declare const noopLogger: Logger;
+
+/**
+ * Public types for the Woku React Native SDK.
+ *
+ * The SDK core is transport- and platform-agnostic: it builds typed
+ * capture payloads and hands them to injectable adapters (HTTP, storage,
+ * audio). React Native apps wire those adapters at init time.
+ */
+/** The two capture flows Woku supports. */
+type CaptureKind = 'woku' | 'nps';
+/** An audio attachment for a text/voice comment. */
+interface AudioAttachment {
+    /** URI or local path to the recorded audio file. */
+    uri: string;
+    /** MIME type, e.g. `audio/m4a`. */
+    mimeType: string;
+    /** Duration in milliseconds, if known. */
+    durationMs?: number;
+}
+/** Who is giving the feedback. Anonymous unless an identifier is set. */
+interface Respondent {
+    email?: string;
+    phone?: string;
+    /** Free-form external id the host app controls (e.g. a CRM id). */
+    externalId?: string;
+}
+/** Input for a Woku capture (1-tap rating 1..5 + optional comment/audio). */
+interface WokuCaptureInput {
+    wokuId: string;
+    /** Integer 1..5. */
+    rating: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    /** Arbitrary context tags attached to the submission. */
+    metadata?: Record<string, unknown>;
+}
+/** Input for an NPS capture (score 0..10 + optional review). */
+interface NpsCaptureInput {
+    npsId: string;
+    /** Integer 0..10. */
+    score: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    metadata?: Record<string, unknown>;
+}
+/** Normalized submission persisted in the offline queue and sent to Woku. */
+interface CaptureSubmission {
+    /** Client-generated idempotency id. */
+    id: string;
+    kind: CaptureKind;
+    companyId: string;
+    targetId: string;
+    rating?: number;
+    score?: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    metadata?: Record<string, unknown>;
+    /** Unix epoch ms when the capture was created on the device. */
+    createdAt: number;
+}
+/** Result of attempting to deliver a submission. */
+interface SubmissionResult {
+    id: string;
+    status: 'sent' | 'queued' | 'failed' | 'quarantined';
+    /** Server id once accepted. */
+    remoteId?: string;
+    error?: string;
+}
+
+interface WokuClientConfig {
+    /** Base URL of the Woku API, e.g. `https://api.woku.app`. */
+    apiUrl: string;
+    /** Public SDK key issued per company for capture ingestion. */
+    publicKey: string;
+    /** Tenant the captures belong to. */
+    companyId: string;
+    /** HTTP transport. Defaults to the global `fetch`. */
+    http?: HttpClient;
+    logger?: Logger;
+    /** Ingest path appended to `apiUrl`. Defaults to `/sdk/v1/captures`. */
+    capturePath?: string;
+}
+/**
+ * Thin, typed transport to the Woku capture ingest endpoint. Stateless:
+ * it turns a normalized {@link CaptureSubmission} into an authenticated
+ * POST and maps the response (incl. quarantine 429) to a result/error.
+ */
+declare class WokuClient {
+    private readonly config;
+    private readonly http;
+    private readonly logger;
+    private readonly endpoint;
+    constructor(config: WokuClientConfig);
+    /**
+     * Sends one submission. Resolves with a `sent` result on 2xx, throws
+     * {@link WokuQuarantineError} on a quarantine 429, {@link WokuNetworkError}
+     * on transport failure, and resolves with a `failed` result on other
+     * non-2xx responses (so the caller can decide to re-queue).
+     */
+    send(submission: CaptureSubmission): Promise<SubmissionResult>;
+    private safeJson;
+}
+
+interface OfflineQueueOptions {
+    storage?: Storage;
+    /** Storage key for the persisted queue. */
+    storageKey?: string;
+    /** Drop a submission after this many failed delivery attempts. */
+    maxAttempts?: number;
+}
+interface FlushResult {
+    sent: number;
+    failed: number;
+    remaining: number;
+    /** Set when flushing stopped early due to quarantine. */
+    quarantined?: boolean;
+}
+/**
+ * Durable, FIFO offline buffer for captures. Persists through an
+ * injectable {@link Storage} so submissions survive app restarts, and
+ * flushes them through a caller-provided `send` function. Pure and
+ * deterministic: no timers, no platform APIs.
+ *
+ * Delivery semantics on flush:
+ *  - `sent`        -> removed from the queue.
+ *  - quarantine    -> flush stops (server is rate-limiting the
+ *                     respondent); items are kept for the next attempt.
+ *  - network error -> attempt count bumped, item kept, flush continues.
+ *  - `failed`      -> attempt count bumped; dropped once maxAttempts is
+ *                     reached so a permanently-bad item can't wedge it.
+ */
+declare class OfflineQueue {
+    private readonly storage;
+    private readonly key;
+    private readonly maxAttempts;
+    private items;
+    constructor(opts?: OfflineQueueOptions);
+    private load;
+    private persist;
+    /** Adds a submission to the tail of the queue (dedup by id). */
+    enqueue(submission: CaptureSubmission): Promise<void>;
+    size(): Promise<number>;
+    /** Returns a copy of the pending submissions (oldest first). */
+    pending(): Promise<CaptureSubmission[]>;
+    /**
+     * 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.
+     */
+    flush(send: (submission: CaptureSubmission) => Promise<SubmissionResult>): Promise<FlushResult>;
+    /** Clears the queue (e.g. on logout). */
+    clear(): Promise<void>;
+}
+
+interface WokuSdkConfig extends WokuClientConfig {
+    /** Storage adapter for the offline queue (MMKV/AsyncStorage in RN). */
+    storage?: Storage;
+    /** Drop a queued submission after this many failed attempts. */
+    maxQueueAttempts?: number;
+}
+/**
+ * Top-level Woku SDK. Wires the typed {@link WokuClient} to a durable
+ * {@link OfflineQueue}: a capture is attempted immediately and, if the
+ * device is offline or the server is unreachable, transparently queued
+ * and retried on the next {@link WokuSdk.flush}.
+ *
+ * @example
+ * const woku = new WokuSdk({
+ *   apiUrl: 'https://api.woku.app',
+ *   publicKey: 'pk_live_...',
+ *   companyId: 'company_123',
+ *   storage: mmkvStorageAdapter,
+ * });
+ * await woku.captureNps({ npsId: 'nps_1', score: 9, comment: 'Great!' });
+ */
+declare class WokuSdk {
+    private readonly client;
+    private readonly queue;
+    private readonly logger;
+    private readonly companyId;
+    constructor(config: WokuSdkConfig);
+    /** Captures a Woku rating (1..5) with optional text/audio comment. */
+    captureWoku(input: WokuCaptureInput): Promise<SubmissionResult>;
+    /** Captures an NPS score (0..10) with optional text/audio review. */
+    captureNps(input: NpsCaptureInput): Promise<SubmissionResult>;
+    /** Retries every queued submission. Safe to call on app foreground or
+     *  when connectivity is regained. */
+    flush(): Promise<FlushResult>;
+    /** Number of submissions waiting to be delivered. */
+    pendingCount(): Promise<number>;
+    /** Clears the offline queue (e.g. on user logout). */
+    clearQueue(): Promise<void>;
+    /**
+     * Tries to send immediately; on quarantine or network failure the
+     * submission is queued for a later flush rather than thrown away.
+     */
+    private deliver;
+}
+
+/** Base error for all SDK failures. */
+declare class WokuError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Thrown when the SDK is misconfigured (missing companyId, etc.). */
+declare class WokuConfigError extends WokuError {
+    constructor(message: string);
+}
+/** Validation failure on a capture input (bad rating/score, etc.). */
+declare class WokuValidationError extends WokuError {
+    constructor(message: string);
+}
+/**
+ * The backend rejected the submission because the respondent is in
+ * quarantine (HTTP 429 with a QUARANTINE_BLOCKED code). Carries the
+ * retry-after hint in seconds when the server provides one.
+ */
+declare class WokuQuarantineError extends WokuError {
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, retryAfterSeconds?: number | undefined);
+}
+/** Network/transport failure; the submission should be retried later. */
+declare class WokuNetworkError extends WokuError {
+    constructor(message: string);
+}
+
+export { type AudioAttachment, type CaptureKind, type CaptureSubmission, type FlushResult, type HttpClient, type HttpRequest, type HttpResponse, InMemoryStorage, type Logger, type NpsCaptureInput, OfflineQueue, type OfflineQueueOptions, type Respondent, type Storage, type SubmissionResult, type WokuCaptureInput, WokuClient, type WokuClientConfig, WokuConfigError, WokuError, WokuNetworkError, WokuQuarantineError, WokuSdk, type WokuSdkConfig, WokuValidationError, fetchHttpClient, noopLogger };

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Injectable adapters. The SDK core never imports React Native or a
+ * concrete HTTP/storage library directly — host apps provide these so
+ * the core stays unit-testable and platform-agnostic.
+ */
+/** Minimal HTTP response the SDK needs. */
+interface HttpResponse {
+    status: number;
+    ok: boolean;
+    json: () => Promise<unknown>;
+    headers: {
+        get: (name: string) => string | null;
+    };
+}
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/** HTTP transport. Defaults to global `fetch`. */
+interface HttpClient {
+    request: (req: HttpRequest) => Promise<HttpResponse>;
+}
+/**
+ * Key/value persistence for the offline queue. React Native apps pass an
+ * MMKV or AsyncStorage-backed adapter; tests use the in-memory one.
+ */
+interface Storage {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+}
+interface Logger {
+    debug: (msg: string, meta?: unknown) => void;
+    warn: (msg: string, meta?: unknown) => void;
+    error: (msg: string, meta?: unknown) => void;
+}
+/** Default HTTP client backed by the global `fetch`. */
+declare const fetchHttpClient: HttpClient;
+/** In-memory storage. Default for tests and ephemeral usage. */
+declare class InMemoryStorage implements Storage {
+    private readonly map;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** No-op logger (default). */
+declare const noopLogger: Logger;
+
+/**
+ * Public types for the Woku React Native SDK.
+ *
+ * The SDK core is transport- and platform-agnostic: it builds typed
+ * capture payloads and hands them to injectable adapters (HTTP, storage,
+ * audio). React Native apps wire those adapters at init time.
+ */
+/** The two capture flows Woku supports. */
+type CaptureKind = 'woku' | 'nps';
+/** An audio attachment for a text/voice comment. */
+interface AudioAttachment {
+    /** URI or local path to the recorded audio file. */
+    uri: string;
+    /** MIME type, e.g. `audio/m4a`. */
+    mimeType: string;
+    /** Duration in milliseconds, if known. */
+    durationMs?: number;
+}
+/** Who is giving the feedback. Anonymous unless an identifier is set. */
+interface Respondent {
+    email?: string;
+    phone?: string;
+    /** Free-form external id the host app controls (e.g. a CRM id). */
+    externalId?: string;
+}
+/** Input for a Woku capture (1-tap rating 1..5 + optional comment/audio). */
+interface WokuCaptureInput {
+    wokuId: string;
+    /** Integer 1..5. */
+    rating: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    /** Arbitrary context tags attached to the submission. */
+    metadata?: Record<string, unknown>;
+}
+/** Input for an NPS capture (score 0..10 + optional review). */
+interface NpsCaptureInput {
+    npsId: string;
+    /** Integer 0..10. */
+    score: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    metadata?: Record<string, unknown>;
+}
+/** Normalized submission persisted in the offline queue and sent to Woku. */
+interface CaptureSubmission {
+    /** Client-generated idempotency id. */
+    id: string;
+    kind: CaptureKind;
+    companyId: string;
+    targetId: string;
+    rating?: number;
+    score?: number;
+    comment?: string;
+    audio?: AudioAttachment;
+    respondent?: Respondent;
+    metadata?: Record<string, unknown>;
+    /** Unix epoch ms when the capture was created on the device. */
+    createdAt: number;
+}
+/** Result of attempting to deliver a submission. */
+interface SubmissionResult {
+    id: string;
+    status: 'sent' | 'queued' | 'failed' | 'quarantined';
+    /** Server id once accepted. */
+    remoteId?: string;
+    error?: string;
+}
+
+interface WokuClientConfig {
+    /** Base URL of the Woku API, e.g. `https://api.woku.app`. */
+    apiUrl: string;
+    /** Public SDK key issued per company for capture ingestion. */
+    publicKey: string;
+    /** Tenant the captures belong to. */
+    companyId: string;
+    /** HTTP transport. Defaults to the global `fetch`. */
+    http?: HttpClient;
+    logger?: Logger;
+    /** Ingest path appended to `apiUrl`. Defaults to `/sdk/v1/captures`. */
+    capturePath?: string;
+}
+/**
+ * Thin, typed transport to the Woku capture ingest endpoint. Stateless:
+ * it turns a normalized {@link CaptureSubmission} into an authenticated
+ * POST and maps the response (incl. quarantine 429) to a result/error.
+ */
+declare class WokuClient {
+    private readonly config;
+    private readonly http;
+    private readonly logger;
+    private readonly endpoint;
+    constructor(config: WokuClientConfig);
+    /**
+     * Sends one submission. Resolves with a `sent` result on 2xx, throws
+     * {@link WokuQuarantineError} on a quarantine 429, {@link WokuNetworkError}
+     * on transport failure, and resolves with a `failed` result on other
+     * non-2xx responses (so the caller can decide to re-queue).
+     */
+    send(submission: CaptureSubmission): Promise<SubmissionResult>;
+    private safeJson;
+}
+
+interface OfflineQueueOptions {
+    storage?: Storage;
+    /** Storage key for the persisted queue. */
+    storageKey?: string;
+    /** Drop a submission after this many failed delivery attempts. */
+    maxAttempts?: number;
+}
+interface FlushResult {
+    sent: number;
+    failed: number;
+    remaining: number;
+    /** Set when flushing stopped early due to quarantine. */
+    quarantined?: boolean;
+}
+/**
+ * Durable, FIFO offline buffer for captures. Persists through an
+ * injectable {@link Storage} so submissions survive app restarts, and
+ * flushes them through a caller-provided `send` function. Pure and
+ * deterministic: no timers, no platform APIs.
+ *
+ * Delivery semantics on flush:
+ *  - `sent`        -> removed from the queue.
+ *  - quarantine    -> flush stops (server is rate-limiting the
+ *                     respondent); items are kept for the next attempt.
+ *  - network error -> attempt count bumped, item kept, flush continues.
+ *  - `failed`      -> attempt count bumped; dropped once maxAttempts is
+ *                     reached so a permanently-bad item can't wedge it.
+ */
+declare class OfflineQueue {
+    private readonly storage;
+    private readonly key;
+    private readonly maxAttempts;
+    private items;
+    constructor(opts?: OfflineQueueOptions);
+    private load;
+    private persist;
+    /** Adds a submission to the tail of the queue (dedup by id). */
+    enqueue(submission: CaptureSubmission): Promise<void>;
+    size(): Promise<number>;
+    /** Returns a copy of the pending submissions (oldest first). */
+    pending(): Promise<CaptureSubmission[]>;
+    /**
+     * 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.
+     */
+    flush(send: (submission: CaptureSubmission) => Promise<SubmissionResult>): Promise<FlushResult>;
+    /** Clears the queue (e.g. on logout). */
+    clear(): Promise<void>;
+}
+
+interface WokuSdkConfig extends WokuClientConfig {
+    /** Storage adapter for the offline queue (MMKV/AsyncStorage in RN). */
+    storage?: Storage;
+    /** Drop a queued submission after this many failed attempts. */
+    maxQueueAttempts?: number;
+}
+/**
+ * Top-level Woku SDK. Wires the typed {@link WokuClient} to a durable
+ * {@link OfflineQueue}: a capture is attempted immediately and, if the
+ * device is offline or the server is unreachable, transparently queued
+ * and retried on the next {@link WokuSdk.flush}.
+ *
+ * @example
+ * const woku = new WokuSdk({
+ *   apiUrl: 'https://api.woku.app',
+ *   publicKey: 'pk_live_...',
+ *   companyId: 'company_123',
+ *   storage: mmkvStorageAdapter,
+ * });
+ * await woku.captureNps({ npsId: 'nps_1', score: 9, comment: 'Great!' });
+ */
+declare class WokuSdk {
+    private readonly client;
+    private readonly queue;
+    private readonly logger;
+    private readonly companyId;
+    constructor(config: WokuSdkConfig);
+    /** Captures a Woku rating (1..5) with optional text/audio comment. */
+    captureWoku(input: WokuCaptureInput): Promise<SubmissionResult>;
+    /** Captures an NPS score (0..10) with optional text/audio review. */
+    captureNps(input: NpsCaptureInput): Promise<SubmissionResult>;
+    /** Retries every queued submission. Safe to call on app foreground or
+     *  when connectivity is regained. */
+    flush(): Promise<FlushResult>;
+    /** Number of submissions waiting to be delivered. */
+    pendingCount(): Promise<number>;
+    /** Clears the offline queue (e.g. on user logout). */
+    clearQueue(): Promise<void>;
+    /**
+     * Tries to send immediately; on quarantine or network failure the
+     * submission is queued for a later flush rather than thrown away.
+     */
+    private deliver;
+}
+
+/** Base error for all SDK failures. */
+declare class WokuError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Thrown when the SDK is misconfigured (missing companyId, etc.). */
+declare class WokuConfigError extends WokuError {
+    constructor(message: string);
+}
+/** Validation failure on a capture input (bad rating/score, etc.). */
+declare class WokuValidationError extends WokuError {
+    constructor(message: string);
+}
+/**
+ * The backend rejected the submission because the respondent is in
+ * quarantine (HTTP 429 with a QUARANTINE_BLOCKED code). Carries the
+ * retry-after hint in seconds when the server provides one.
+ */
+declare class WokuQuarantineError extends WokuError {
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, retryAfterSeconds?: number | undefined);
+}
+/** Network/transport failure; the submission should be retried later. */
+declare class WokuNetworkError extends WokuError {
+    constructor(message: string);
+}
+
+export { type AudioAttachment, type CaptureKind, type CaptureSubmission, type FlushResult, type HttpClient, type HttpRequest, type HttpResponse, InMemoryStorage, type Logger, type NpsCaptureInput, OfflineQueue, type OfflineQueueOptions, type Respondent, type Storage, type SubmissionResult, type WokuCaptureInput, WokuClient, type WokuClientConfig, WokuConfigError, WokuError, WokuNetworkError, WokuQuarantineError, WokuSdk, type WokuSdkConfig, WokuValidationError, fetchHttpClient, noopLogger };