@lorikeetai/react-native-sdk 2.0.0-alpha.3 → 2.0.0

package/dist/index.d.cts

@@ -13,13 +13,21 @@ type ConversationMetadata = Record<string, unknown>;
  * have: `Customisations` then degraded to `any` and typed nothing.
  * `ConversationMetadata` is duplicated here for the same reason.
  *
- * `src/customisations.web-sdk-parity.ts` fails the build if the two drift.
+ * `src/customisations.web-sdk-parity.ts` fails `typecheck` if the two drift. Not
+ * the build: that file is unreachable from `index.ts`, so the declaration build
+ * never sees it.
  *
- * Fields that only mean something on a web page, the viewport sizes and the
- * launcher button, are kept so the page's behaviour is unchanged and so a host
- * sharing one configuration object with its web widget still type-checks.
+ * Fields that only mean something on a web page are kept so the page's behaviour
+ * is unchanged and so a host sharing one configuration object with its web
+ * widget still type-checks. The viewport sizes, the launcher button and `mode`
+ * are all read by the web SDK rather than by the page, so none of them reaches
+ * anything this SDK renders.
+ */
+/**
+ * Sizing for one viewport. Mostly desktop: the page is full-screen on mobile, so
+ * `height`, `width` and `borderRadius` are read for `desktop` alone, while
+ * `topClearance` and `default_open` are read for whichever viewport applies.
  */
-/** Sizing for one viewport. Desktop only: the page is full-screen on mobile. */
 interface ViewportCustomisations {
   /** Clamped to a 2rem maximum. */
   borderRadius?: string;
@@ -37,7 +45,10 @@ interface Customisations {
   desktop?: ViewportCustomisations;
   /**
    * Which header the customer gets, not whether there is one. `true` hides the
-   * page's own; `false` keeps it, and it carries Close and End chat.
+   * page's own; `false` keeps it, and with it the page's way out of a
+   * conversation. Ending and minimising are what that header is for, and which
+   * controls it offers depends on the subscriber's configuration, so hiding it
+   * leaves the customer no way to end or minimise unless the host supplies one.
    *
    * What replaces a hidden one is the host's business, so there is no one
    * default to quote. `LorikeetWidgetView` substitutes its own header, a title
@@ -53,12 +64,17 @@ interface Customisations {
   messages?: {
     /** Shown when the widget is in an unexpectedly failed state. */
     failOver?: string;
-    /** Shown when live chat has been switched off deliberately. */
+    /**
+     * Shown when live chat has been switched off deliberately. Reachable only
+     * where the live agent bridge is on for the subscriber; without it the widget
+     * has no unavailable state for this to label.
+     */
     unavailable?: string;
     /**
      * Replaces the line under "Someone is taking a look", for a conversation
      * handed to a person. Say where the reply will come from when the default
-     * should not promise it.
+     * should not promise it. Shown only where the live chat experience is on,
+     * which is what puts the notice on screen in the first place.
      */
     escalated?: string;
   };
@@ -103,9 +119,10 @@ interface CustomisationTheme {
   /**
    * Google Fonts CSS URL declaring the `@font-face` rules for `fontFamily`.
    * The page ships Inter only, so a brand font the device lacks falls back
-   * unless its files are loaded. Host must be `fonts.googleapis.com`, path
-   * `/css` or `/css2`, and only `family` and `display` params; anything else is
-   * ignored.
+   * unless its files are loaded. Must be https, host `fonts.googleapis.com`,
+   * path `/css` or `/css2`, and carry `family` plus at most a standard
+   * `display`. A URL failing any of that is dropped whole rather than trimmed,
+   * so one stray query param means no font loads at all.
    */
   fontUrl?: string;
   /**
@@ -130,14 +147,15 @@ interface CustomisationTheme {
  * Names follow the web SDK's (`LorikeetEvent` in `@lorikeetai/web-sdk/types`)
  * wherever it has one, because a host that integrates both should not have to
  * learn two vocabularies. The rest cover what the page tells a host that owns
- * its own layout and storage, which on web the SDK handles internally and never
- * surfaces: the close handshake, the persistence messages, the logout
- * confirmation, and error codes. `logout_failed` is the one the SDK reports
- * itself, for a page that said nothing when it had to.
+ * its own layout and storage, which the web SDK largely handles for itself: it
+ * surfaces a close without its reason, a created ticket without the stored pair
+ * behind it, and `EXPIRED_TOKEN` alone of the error codes. `logout_failed` is
+ * the one the SDK reports itself, for a page that said nothing when it had to.
  *
- * `token_expiry` is deliberately absent. The credential model it belongs to is
- * being rewritten, and an event is the hardest thing to take back. Nothing
- * carrying a credential is translated at all, for the same reason.
+ * `token_expiry` is deliberately absent, and the anonymous session token with
+ * it. The credential model they belong to is being rewritten, and an event is
+ * the hardest thing to take back. `persist_session` is translated despite
+ * carrying a credential, because a resume cannot be rebuilt without it.
  */
 type LorikeetWidgetEvent =
 /** The page is up and the conversation is usable. */
@@ -146,7 +164,8 @@ type LorikeetWidgetEvent =
 } |
 /**
  * A ticket that did not exist before this page loaded. Once per ticket, and
- * never for a resume, matching the web SDK.
+ * never for a resume. The web SDK suppresses a resume too, but counts once
+ * per session rather than per ticket, so this is the stricter of the two.
  */
 {
   type: 'ticket_created';
@@ -170,12 +189,18 @@ type LorikeetWidgetEvent =
   markUnread?: boolean;
 } |
 /**
- * The page closed itself, and why. `ended_by_customer` is followed by a
- * `new_chat`, seconds later, so a host that tears down here never sees the
- * rest of the handshake. `minimised` has nothing behind it: the conversation
- * is intact and hiding it is enough.
+ * The page closed itself, and why. `ended_by_customer` is usually followed by
+ * a `new_chat`, once the end and any CSAT have settled, so a host that tears
+ * down here never sees the rest of the handshake. Usually rather than always:
+ * a CSAT rating that fails holds the replacement back, and nothing but another
+ * close releases it. `minimised` has nothing behind it: the conversation is
+ * intact and hiding it is enough.
  *
- * `reason` is absent from a page older than the release that added it.
+ * `reason` is absent from a page older than the release that added it, from one
+ * whose host lifecycle events are switched off, and from the closes the page
+ * makes on its own behalf, its error boundary among them. An absent reason
+ * reads as an end, so a minimise is only distinguishable when the page names
+ * it.
  */
 {
   type: 'close';
@@ -186,6 +211,9 @@ type LorikeetWidgetEvent =
  * or it timed out. Nothing follows, and nothing is asking the host to hide
  * anything. Left unhandled, this is the customer stranded on a conversation
  * that can no longer be used.
+ *
+ * Reported only by a page whose host lifecycle events are on, so it is not
+ * the only way an ended conversation can reach a host.
  */
 {
   type: 'conversation_ended';
@@ -199,13 +227,16 @@ type LorikeetWidgetEvent =
 } |
 /**
  * Store this against the customer, alongside the session. A resume needs both:
- * the ticket alone fails with `CUSTOMER_ID_MISSING`.
+ * the ticket alone is refused, usually as `CUSTOMER_ID_MISSING`.
  */
 {
   type: 'persist_ticket_id';
   ticketId: string;
 } |
-/** The other half of the stored pair. Arrives separately and in no order. */
+/**
+ * The other half of the stored pair, as its own message. The SDK does not rely
+ * on which half arrives first, and neither should a host.
+ */
 {
   type: 'persist_session';
   session: string;
@@ -297,10 +328,16 @@ type LorikeetWidgetWebViewProps = {
   /**
    * What the page reported, as typed events rather than raw bridge messages.
    *
-   * This component reports; it does not act. A host composing it owns its own
-   * URL, layout and storage, so hiding on a close, rebuilding a resume URL or
-   * recovering from process loss are all theirs to do. `LorikeetWidgetView`
-   * consumes this same path and acts on top of it, because it owns the URL.
+   * This component acts on navigation alone; about the conversation it does
+   * nothing. A top-level navigation leaving the widget's origin goes to the OS,
+   * unless your own `webviewProps.onShouldStartLoadWithRequest` returns `false`
+   * for it, which is taken as a decision and not second-guessed. A navigation
+   * the WebView reports as a subframe stays in the page, since a frame the page
+   * embedded is not a link the customer followed. A host
+   * composing it owns its own URL, layout and storage, so hiding on a close,
+   * rebuilding a resume URL or recovering from process loss are all theirs to
+   * do. `LorikeetWidgetView` consumes this same path and acts on top of it,
+   * because it owns the URL.
    */
   onEvent?: (event: LorikeetWidgetEvent) => void;
 };
@@ -339,17 +376,27 @@ type LorikeetWidgetHandle = {
    * host holding what it passed at mount can be holding a conversation that no
    * longer exists.
    *
-   * `null` means exactly that the widget has nothing to resume: no conversation
-   * reported yet, only half of one, the credentials have moved on, or the
-   * customer has been logged out. It does not mean the conversation is over. A
-   * conversation the customer ended is still reported, because that is still
-   * what the widget is on and what its own recovery would resume; `close` and
-   * its `reason` are how you hear that it ended.
+   * The ticket is the half that decides. `null` means no ticket has been
+   * reported for these credentials: none yet, a session on its own, the
+   * credentials have moved on, or the customer has been logged out. It does not
+   * mean the conversation is over. A conversation the customer ended is still
+   * reported, because that is still what the widget is on and what its own
+   * recovery would resume; `close` and its `reason` are how you hear that it
+   * ended.
+   *
+   * A reported ticket with no `session` yet is not `null`, and is also not
+   * resumable on its own: the ticket route needs both. Treat `session` as
+   * outstanding rather than absent until it arrives.
    *
-   * Reports what is on screen, so inside an `onEvent` handler it is still what
-   * was on screen before that event: read `reason` on the `close` rather than
-   * calling this from the handler. Read it again after a change rather than
-   * caching what it said.
+   * Reads live, so inside an `onEvent` handler for `persist_ticket_id` or
+   * `persist_session` it has already taken that event into account. What it will
+   * not do is answer before a ticket exists, and the page normally sends the
+   * session first, so the `persist_session` handler sees `null`. Store each half
+   * from its own event rather than asking here.
+   *
+   * `minimised` moves with a render instead, so inside a `close` handler it
+   * describes what was on screen before: read `reason` on the `close` rather
+   * than this. Read it again after a change rather than caching what it said.
    */
   getConversation: () => {
     minimised: boolean;
@@ -442,14 +489,15 @@ type LorikeetWidgetViewProps = {
    * Resume this conversation instead of starting a new one. Without it the
    * widget boots `/widget`, which mints a fresh ticket on every mount.
    *
-   * Take it from the `persistLorikeetTicketId` message and store it yourself;
-   * the SDK has no storage of its own.
+   * Take it from the `persist_ticket_id` event, or from `getConversation()`, and
+   * store it yourself; the SDK has no storage of its own.
    */
   ticketId?: string;
   /**
-   * The session token last reported by `persistLorikeetSession`, stored
-   * alongside `ticketId`. The ticket route needs it to authorise a WebView that
-   * has no cookie yet, so a resume without it fails with CUSTOMER_ID_MISSING.
+   * The session token last reported by `persist_session`, stored alongside
+   * `ticketId`. The ticket route needs it to authorise a WebView that has no
+   * cookie yet, so a resume without it is refused, usually as
+   * CUSTOMER_ID_MISSING.
    */
   session?: string;
   /**
@@ -501,9 +549,14 @@ declare class LorikeetClient {
 //#endregion
 //#region src/errors.d.ts
 /**
- * Codes the chat page posts to the host as `{ type: 'error', error: CODE }`.
- * Mirrored here because the page publishes them nowhere else, so a host would
- * otherwise be matching on strings it discovered by observation.
+ * The chat page's error vocabulary, as it reaches a host in
+ * `{ type: 'error', error: CODE }`. Mirrored here because the page publishes it
+ * nowhere else, so a host would otherwise be matching on strings it discovered
+ * by observation.
+ *
+ * The page's own list rather than a list of codes seen in the wild:
+ * `MISSING_PUBLIC_KEY` has no producer today, and is kept because narrowing this
+ * would be a breaking change.
  */
 declare const LORIKEET_ERROR_CODES: readonly ["MISSING_TOKEN", "CORRUPT_TOKEN_DATA", "DECRYPT_FAILED", "EXPIRED_TOKEN", "MALFORMED_TOKEN", "MISSING_PUBLIC_KEY", "UNKNOWN_PUBLIC_KEY", "CUSTOMER_ID_CONFLICT", "CUSTOMER_ID_MISSING", "FATAL_ERROR", "INVALID_SESSION", "DOMAIN_NOT_ALLOWED", "TICKET_NOT_FOUND"];
 type LorikeetErrorCode = (typeof LORIKEET_ERROR_CODES)[number];

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/conversation-metadata.ts","../src/customisations.ts","../src/events.ts","../src/types.ts","../src/widget.tsx","../src/client.ts","../src/errors.ts","../src/lifecycle.ts"],"mappings":";;;KAEY,uBAAuB;;;;;;;;;;;;;;;;;;;UCezB;;EAER;EACA;;EAEA;;EAEA;EACA;;UAGe;;EAEf;EACA;EACA,UAAU;;;;;;;;;;;;EAYV;;EAEA;EACA;EACA;;IAEE;;IAEA;;;;;;IAMA;;EAEF,SAAS;EACT;;;;;;;EAOA;IACE;IACA;IACA;IACA;IACA;;IAEA;;;EAGF;EACA,QAAQ;EACR;;EAEA;;UAGe;;;;;;EAMf;EACA;;EAEA;EACA;;EAEA;EACA;;;;;;;;EAQA;;;;;EAKA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;KCxGU;;;EAEN;;;;;;;EAKA;EAAwB;;;;EAExB;;;;;;;;;;;;EAUA;EAAuB;;;;;;;;;;;EASvB;EAAe;;;;;;;;;EAOf;;;;;;;EAKA;;;;;;;EAKA;EAA2B;;;;EAE3B;EAAyB;;;;;;;;;;;;;;;;EAczB;;;;;;;;;;;;EAUA;;;;EAEA;EAAe;;;;;;;;;;;;;EAYf;EACA;EACA;;;KAIM;;;UCnGK;;;;EAIf;;;;EAIA,iBAAiB;;;;;EAKjB,WAAW;;;;EAIX;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA,eAAe;;;;;;;;;EASf,WAAW,OAAO;;KAGR;;;;EAIV;;;;EAIA,QAAQ,UAAU;;;;EAIlB,OAAO,MAAM;;;;EAIb;;;;;;;KAQU;;;;;;;;;;;;;;;;;;;;;;;;EAwBV;IACE;IACA;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BF;;;;;;;;;;;;;EAaA;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA;;;;;;;;;;;;;EAaA,oBAAoB,OAAO;;;;;EAK3B,WAAW,OAAO;;;;EAIlB,iBAAiB;;;;EAIjB;IACE,SAAS,UAAU;;;;;;;;;EASrB;;;;;;EAMA;;;;;;EAMA,WAAW;;;;;;;EAOX,eAAe;;;;cC3HJ,uCAAqB,0BAAA,6CAAA,cAAA;cA2HrB,yBAAwB,OAAA,OAAA,MAAA,eAKlC,8CAAyB,IAAA;cAYf,oCAAkB,0BAAA,0CAAA,cAAA;;;cCjOlB;EACX;EACA,gBAAgB;EAChB,UAAU;EACV;EAEY,cACV,gBACA,UACA,UACA,cACC;EAeH,kBAAiB,gBAAA,eAAA,OAAA,WAAA;IAOf;IACA;IACA;IACA;IACA;;;;;;;;;;;;EAmDF;;;;;;;;;cCxFW;KAgBD,4BAA4B;;iBAexB,2BAA2B;iBAK3B,uBAAuB;;;;;;;;;;;;;;cCjB1B"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/conversation-metadata.ts","../src/customisations.ts","../src/events.ts","../src/types.ts","../src/widget.tsx","../src/client.ts","../src/errors.ts","../src/lifecycle.ts"],"mappings":";;;KAEY,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;UCuBzB;;EAER;EACA;;EAEA;;EAEA;EACA;;UAGe;;EAEf;EACA;EACA,UAAU;;;;;;;;;;;;;;;EAeV;;EAEA;EACA;EACA;;IAEE;;;;;;IAMA;;;;;;;IAOA;;EAEF,SAAS;EACT;;;;;;;EAOA;IACE;IACA;IACA;IACA;IACA;;IAEA;;;EAGF;EACA,QAAQ;EACR;;EAEA;;UAGe;;;;;;EAMf;EACA;;EAEA;EACA;;EAEA;EACA;;;;;;;;;EASA;;;;;EAKA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;;KCxHU;;;EAEN;;;;;;;;EAMA;EAAwB;;;;EAExB;;;;;;;;;;;;EAUA;EAAuB;;;;;;;;;;;;;;;;;EAevB;EAAe;;;;;;;;;;;;EAUf;;;;;;;EAKA;;;;;;;EAKA;EAA2B;;;;;;;EAK3B;EAAyB;;;;;;;;;;;;;;;;EAczB;;;;;;;;;;;;EAUA;;;;EAEA;EAAe;;;;;;;;;;;;;EAYf;EACA;EACA;;;KAIM;;;UCjHK;;;;EAIf;;;;EAIA,iBAAiB;;;;;EAKjB,WAAW;;;;EAIX;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA,eAAe;;;;;;;;;;;;;;;EAef,WAAW,OAAO;;KAGR;;;;EAIV;;;;EAIA,QAAQ,UAAU;;;;EAIlB,OAAO,MAAM;;;;EAIb;;;;;;;KAQU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCV;IACE;IACA;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BF;;;;;;;;;;;;;EAaA;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA;;;;;;;;;;;;;EAaA,oBAAoB,OAAO;;;;;EAK3B,WAAW,OAAO;;;;EAIlB,iBAAiB;;;;EAIjB;IACE,SAAS,UAAU;;;;;;;;;EASrB;;;;;;;EAOA;;;;;;EAMA,WAAW;;;;;;;EAOX,eAAe;;;;cC5IJ,uCAAqB,0BAAA,6CAAA,cAAA;cA2HrB,yBAAwB,OAAA,OAAA,MAAA,eAKlC,8CAAyB,IAAA;cAYf,oCAAkB,0BAAA,0CAAA,cAAA;;;cCjOlB;EACX;EACA,gBAAgB;EAChB,UAAU;EACV;EAEY,cACV,gBACA,UACA,UACA,cACC;EAeH,kBAAiB,gBAAA,eAAA,OAAA,WAAA;IAOf;IACA;IACA;IACA;IACA;;;;;;;;;;;;EAmDF;;;;;;;;;;;;;;cCnFW;KAgBD,4BAA4B;;iBAexB,2BAA2B;iBAK3B,uBAAuB;;;;;;;;;;;;;;cCtB1B"}

package/dist/index.d.ts

@@ -13,13 +13,21 @@ type ConversationMetadata = Record<string, unknown>;
  * have: `Customisations` then degraded to `any` and typed nothing.
  * `ConversationMetadata` is duplicated here for the same reason.
  *
- * `src/customisations.web-sdk-parity.ts` fails the build if the two drift.
+ * `src/customisations.web-sdk-parity.ts` fails `typecheck` if the two drift. Not
+ * the build: that file is unreachable from `index.ts`, so the declaration build
+ * never sees it.
  *
- * Fields that only mean something on a web page, the viewport sizes and the
- * launcher button, are kept so the page's behaviour is unchanged and so a host
- * sharing one configuration object with its web widget still type-checks.
+ * Fields that only mean something on a web page are kept so the page's behaviour
+ * is unchanged and so a host sharing one configuration object with its web
+ * widget still type-checks. The viewport sizes, the launcher button and `mode`
+ * are all read by the web SDK rather than by the page, so none of them reaches
+ * anything this SDK renders.
+ */
+/**
+ * Sizing for one viewport. Mostly desktop: the page is full-screen on mobile, so
+ * `height`, `width` and `borderRadius` are read for `desktop` alone, while
+ * `topClearance` and `default_open` are read for whichever viewport applies.
  */
-/** Sizing for one viewport. Desktop only: the page is full-screen on mobile. */
 interface ViewportCustomisations {
   /** Clamped to a 2rem maximum. */
   borderRadius?: string;
@@ -37,7 +45,10 @@ interface Customisations {
   desktop?: ViewportCustomisations;
   /**
    * Which header the customer gets, not whether there is one. `true` hides the
-   * page's own; `false` keeps it, and it carries Close and End chat.
+   * page's own; `false` keeps it, and with it the page's way out of a
+   * conversation. Ending and minimising are what that header is for, and which
+   * controls it offers depends on the subscriber's configuration, so hiding it
+   * leaves the customer no way to end or minimise unless the host supplies one.
    *
    * What replaces a hidden one is the host's business, so there is no one
    * default to quote. `LorikeetWidgetView` substitutes its own header, a title
@@ -53,12 +64,17 @@ interface Customisations {
   messages?: {
     /** Shown when the widget is in an unexpectedly failed state. */
     failOver?: string;
-    /** Shown when live chat has been switched off deliberately. */
+    /**
+     * Shown when live chat has been switched off deliberately. Reachable only
+     * where the live agent bridge is on for the subscriber; without it the widget
+     * has no unavailable state for this to label.
+     */
     unavailable?: string;
     /**
      * Replaces the line under "Someone is taking a look", for a conversation
      * handed to a person. Say where the reply will come from when the default
-     * should not promise it.
+     * should not promise it. Shown only where the live chat experience is on,
+     * which is what puts the notice on screen in the first place.
      */
     escalated?: string;
   };
@@ -103,9 +119,10 @@ interface CustomisationTheme {
   /**
    * Google Fonts CSS URL declaring the `@font-face` rules for `fontFamily`.
    * The page ships Inter only, so a brand font the device lacks falls back
-   * unless its files are loaded. Host must be `fonts.googleapis.com`, path
-   * `/css` or `/css2`, and only `family` and `display` params; anything else is
-   * ignored.
+   * unless its files are loaded. Must be https, host `fonts.googleapis.com`,
+   * path `/css` or `/css2`, and carry `family` plus at most a standard
+   * `display`. A URL failing any of that is dropped whole rather than trimmed,
+   * so one stray query param means no font loads at all.
    */
   fontUrl?: string;
   /**
@@ -130,14 +147,15 @@ interface CustomisationTheme {
  * Names follow the web SDK's (`LorikeetEvent` in `@lorikeetai/web-sdk/types`)
  * wherever it has one, because a host that integrates both should not have to
  * learn two vocabularies. The rest cover what the page tells a host that owns
- * its own layout and storage, which on web the SDK handles internally and never
- * surfaces: the close handshake, the persistence messages, the logout
- * confirmation, and error codes. `logout_failed` is the one the SDK reports
- * itself, for a page that said nothing when it had to.
+ * its own layout and storage, which the web SDK largely handles for itself: it
+ * surfaces a close without its reason, a created ticket without the stored pair
+ * behind it, and `EXPIRED_TOKEN` alone of the error codes. `logout_failed` is
+ * the one the SDK reports itself, for a page that said nothing when it had to.
  *
- * `token_expiry` is deliberately absent. The credential model it belongs to is
- * being rewritten, and an event is the hardest thing to take back. Nothing
- * carrying a credential is translated at all, for the same reason.
+ * `token_expiry` is deliberately absent, and the anonymous session token with
+ * it. The credential model they belong to is being rewritten, and an event is
+ * the hardest thing to take back. `persist_session` is translated despite
+ * carrying a credential, because a resume cannot be rebuilt without it.
  */
 type LorikeetWidgetEvent =
 /** The page is up and the conversation is usable. */
@@ -146,7 +164,8 @@ type LorikeetWidgetEvent =
 } |
 /**
  * A ticket that did not exist before this page loaded. Once per ticket, and
- * never for a resume, matching the web SDK.
+ * never for a resume. The web SDK suppresses a resume too, but counts once
+ * per session rather than per ticket, so this is the stricter of the two.
  */
 {
   type: 'ticket_created';
@@ -170,12 +189,18 @@ type LorikeetWidgetEvent =
   markUnread?: boolean;
 } |
 /**
- * The page closed itself, and why. `ended_by_customer` is followed by a
- * `new_chat`, seconds later, so a host that tears down here never sees the
- * rest of the handshake. `minimised` has nothing behind it: the conversation
- * is intact and hiding it is enough.
+ * The page closed itself, and why. `ended_by_customer` is usually followed by
+ * a `new_chat`, once the end and any CSAT have settled, so a host that tears
+ * down here never sees the rest of the handshake. Usually rather than always:
+ * a CSAT rating that fails holds the replacement back, and nothing but another
+ * close releases it. `minimised` has nothing behind it: the conversation is
+ * intact and hiding it is enough.
  *
- * `reason` is absent from a page older than the release that added it.
+ * `reason` is absent from a page older than the release that added it, from one
+ * whose host lifecycle events are switched off, and from the closes the page
+ * makes on its own behalf, its error boundary among them. An absent reason
+ * reads as an end, so a minimise is only distinguishable when the page names
+ * it.
  */
 {
   type: 'close';
@@ -186,6 +211,9 @@ type LorikeetWidgetEvent =
  * or it timed out. Nothing follows, and nothing is asking the host to hide
  * anything. Left unhandled, this is the customer stranded on a conversation
  * that can no longer be used.
+ *
+ * Reported only by a page whose host lifecycle events are on, so it is not
+ * the only way an ended conversation can reach a host.
  */
 {
   type: 'conversation_ended';
@@ -199,13 +227,16 @@ type LorikeetWidgetEvent =
 } |
 /**
  * Store this against the customer, alongside the session. A resume needs both:
- * the ticket alone fails with `CUSTOMER_ID_MISSING`.
+ * the ticket alone is refused, usually as `CUSTOMER_ID_MISSING`.
  */
 {
   type: 'persist_ticket_id';
   ticketId: string;
 } |
-/** The other half of the stored pair. Arrives separately and in no order. */
+/**
+ * The other half of the stored pair, as its own message. The SDK does not rely
+ * on which half arrives first, and neither should a host.
+ */
 {
   type: 'persist_session';
   session: string;
@@ -297,10 +328,16 @@ type LorikeetWidgetWebViewProps = {
   /**
    * What the page reported, as typed events rather than raw bridge messages.
    *
-   * This component reports; it does not act. A host composing it owns its own
-   * URL, layout and storage, so hiding on a close, rebuilding a resume URL or
-   * recovering from process loss are all theirs to do. `LorikeetWidgetView`
-   * consumes this same path and acts on top of it, because it owns the URL.
+   * This component acts on navigation alone; about the conversation it does
+   * nothing. A top-level navigation leaving the widget's origin goes to the OS,
+   * unless your own `webviewProps.onShouldStartLoadWithRequest` returns `false`
+   * for it, which is taken as a decision and not second-guessed. A navigation
+   * the WebView reports as a subframe stays in the page, since a frame the page
+   * embedded is not a link the customer followed. A host
+   * composing it owns its own URL, layout and storage, so hiding on a close,
+   * rebuilding a resume URL or recovering from process loss are all theirs to
+   * do. `LorikeetWidgetView` consumes this same path and acts on top of it,
+   * because it owns the URL.
    */
   onEvent?: (event: LorikeetWidgetEvent) => void;
 };
@@ -339,17 +376,27 @@ type LorikeetWidgetHandle = {
    * host holding what it passed at mount can be holding a conversation that no
    * longer exists.
    *
-   * `null` means exactly that the widget has nothing to resume: no conversation
-   * reported yet, only half of one, the credentials have moved on, or the
-   * customer has been logged out. It does not mean the conversation is over. A
-   * conversation the customer ended is still reported, because that is still
-   * what the widget is on and what its own recovery would resume; `close` and
-   * its `reason` are how you hear that it ended.
+   * The ticket is the half that decides. `null` means no ticket has been
+   * reported for these credentials: none yet, a session on its own, the
+   * credentials have moved on, or the customer has been logged out. It does not
+   * mean the conversation is over. A conversation the customer ended is still
+   * reported, because that is still what the widget is on and what its own
+   * recovery would resume; `close` and its `reason` are how you hear that it
+   * ended.
+   *
+   * A reported ticket with no `session` yet is not `null`, and is also not
+   * resumable on its own: the ticket route needs both. Treat `session` as
+   * outstanding rather than absent until it arrives.
    *
-   * Reports what is on screen, so inside an `onEvent` handler it is still what
-   * was on screen before that event: read `reason` on the `close` rather than
-   * calling this from the handler. Read it again after a change rather than
-   * caching what it said.
+   * Reads live, so inside an `onEvent` handler for `persist_ticket_id` or
+   * `persist_session` it has already taken that event into account. What it will
+   * not do is answer before a ticket exists, and the page normally sends the
+   * session first, so the `persist_session` handler sees `null`. Store each half
+   * from its own event rather than asking here.
+   *
+   * `minimised` moves with a render instead, so inside a `close` handler it
+   * describes what was on screen before: read `reason` on the `close` rather
+   * than this. Read it again after a change rather than caching what it said.
    */
   getConversation: () => {
     minimised: boolean;
@@ -442,14 +489,15 @@ type LorikeetWidgetViewProps = {
    * Resume this conversation instead of starting a new one. Without it the
    * widget boots `/widget`, which mints a fresh ticket on every mount.
    *
-   * Take it from the `persistLorikeetTicketId` message and store it yourself;
-   * the SDK has no storage of its own.
+   * Take it from the `persist_ticket_id` event, or from `getConversation()`, and
+   * store it yourself; the SDK has no storage of its own.
    */
   ticketId?: string;
   /**
-   * The session token last reported by `persistLorikeetSession`, stored
-   * alongside `ticketId`. The ticket route needs it to authorise a WebView that
-   * has no cookie yet, so a resume without it fails with CUSTOMER_ID_MISSING.
+   * The session token last reported by `persist_session`, stored alongside
+   * `ticketId`. The ticket route needs it to authorise a WebView that has no
+   * cookie yet, so a resume without it is refused, usually as
+   * CUSTOMER_ID_MISSING.
    */
   session?: string;
   /**
@@ -501,9 +549,14 @@ declare class LorikeetClient {
 //#endregion
 //#region src/errors.d.ts
 /**
- * Codes the chat page posts to the host as `{ type: 'error', error: CODE }`.
- * Mirrored here because the page publishes them nowhere else, so a host would
- * otherwise be matching on strings it discovered by observation.
+ * The chat page's error vocabulary, as it reaches a host in
+ * `{ type: 'error', error: CODE }`. Mirrored here because the page publishes it
+ * nowhere else, so a host would otherwise be matching on strings it discovered
+ * by observation.
+ *
+ * The page's own list rather than a list of codes seen in the wild:
+ * `MISSING_PUBLIC_KEY` has no producer today, and is kept because narrowing this
+ * would be a breaking change.
  */
 declare const LORIKEET_ERROR_CODES: readonly ["MISSING_TOKEN", "CORRUPT_TOKEN_DATA", "DECRYPT_FAILED", "EXPIRED_TOKEN", "MALFORMED_TOKEN", "MISSING_PUBLIC_KEY", "UNKNOWN_PUBLIC_KEY", "CUSTOMER_ID_CONFLICT", "CUSTOMER_ID_MISSING", "FATAL_ERROR", "INVALID_SESSION", "DOMAIN_NOT_ALLOWED", "TICKET_NOT_FOUND"];
 type LorikeetErrorCode = (typeof LORIKEET_ERROR_CODES)[number];

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/conversation-metadata.ts","../src/customisations.ts","../src/events.ts","../src/types.ts","../src/widget.tsx","../src/client.ts","../src/errors.ts","../src/lifecycle.ts"],"mappings":";;;KAEY,uBAAuB;;;;;;;;;;;;;;;;;;;UCezB;;EAER;EACA;;EAEA;;EAEA;EACA;;UAGe;;EAEf;EACA;EACA,UAAU;;;;;;;;;;;;EAYV;;EAEA;EACA;EACA;;IAEE;;IAEA;;;;;;IAMA;;EAEF,SAAS;EACT;;;;;;;EAOA;IACE;IACA;IACA;IACA;IACA;;IAEA;;;EAGF;EACA,QAAQ;EACR;;EAEA;;UAGe;;;;;;EAMf;EACA;;EAEA;EACA;;EAEA;EACA;;;;;;;;EAQA;;;;;EAKA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;KCxGU;;;EAEN;;;;;;;EAKA;EAAwB;;;;EAExB;;;;;;;;;;;;EAUA;EAAuB;;;;;;;;;;;EASvB;EAAe;;;;;;;;;EAOf;;;;;;;EAKA;;;;;;;EAKA;EAA2B;;;;EAE3B;EAAyB;;;;;;;;;;;;;;;;EAczB;;;;;;;;;;;;EAUA;;;;EAEA;EAAe;;;;;;;;;;;;;EAYf;EACA;EACA;;;KAIM;;;UCnGK;;;;EAIf;;;;EAIA,iBAAiB;;;;;EAKjB,WAAW;;;;EAIX;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA,eAAe;;;;;;;;;EASf,WAAW,OAAO;;KAGR;;;;EAIV;;;;EAIA,QAAQ,UAAU;;;;EAIlB,OAAO,MAAM;;;;EAIb;;;;;;;KAQU;;;;;;;;;;;;;;;;;;;;;;;;EAwBV;IACE;IACA;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BF;;;;;;;;;;;;;EAaA;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA;;;;;;;;;;;;;EAaA,oBAAoB,OAAO;;;;;EAK3B,WAAW,OAAO;;;;EAIlB,iBAAiB;;;;EAIjB;IACE,SAAS,UAAU;;;;;;;;;EASrB;;;;;;EAMA;;;;;;EAMA,WAAW;;;;;;;EAOX,eAAe;;;;cC3HJ,uCAAqB,0BAAA,6CAAA,cAAA;cA2HrB,yBAAwB,OAAA,OAAA,MAAA,eAKlC,8CAAyB,IAAA;cAYf,oCAAkB,0BAAA,0CAAA,cAAA;;;cCjOlB;EACX;EACA,gBAAgB;EAChB,UAAU;EACV;EAEY,cACV,gBACA,UACA,UACA,cACC;EAeH,kBAAiB,gBAAA,eAAA,OAAA,WAAA;IAOf;IACA;IACA;IACA;IACA;;;;;;;;;;;;EAmDF;;;;;;;;;cCxFW;KAgBD,4BAA4B;;iBAexB,2BAA2B;iBAK3B,uBAAuB;;;;;;;;;;;;;;cCjB1B"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/conversation-metadata.ts","../src/customisations.ts","../src/events.ts","../src/types.ts","../src/widget.tsx","../src/client.ts","../src/errors.ts","../src/lifecycle.ts"],"mappings":";;;KAEY,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;UCuBzB;;EAER;EACA;;EAEA;;EAEA;EACA;;UAGe;;EAEf;EACA;EACA,UAAU;;;;;;;;;;;;;;;EAeV;;EAEA;EACA;EACA;;IAEE;;;;;;IAMA;;;;;;;IAOA;;EAEF,SAAS;EACT;;;;;;;EAOA;IACE;IACA;IACA;IACA;IACA;;IAEA;;;EAGF;EACA,QAAQ;EACR;;EAEA;;UAGe;;;;;;EAMf;EACA;;EAEA;EACA;;EAEA;EACA;;;;;;;;;EASA;;;;;EAKA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;;KCxHU;;;EAEN;;;;;;;;EAMA;EAAwB;;;;EAExB;;;;;;;;;;;;EAUA;EAAuB;;;;;;;;;;;;;;;;;EAevB;EAAe;;;;;;;;;;;;EAUf;;;;;;;EAKA;;;;;;;EAKA;EAA2B;;;;;;;EAK3B;EAAyB;;;;;;;;;;;;;;;;EAczB;;;;;;;;;;;;EAUA;;;;EAEA;EAAe;;;;;;;;;;;;;EAYf;EACA;EACA;;;KAIM;;;UCjHK;;;;EAIf;;;;EAIA,iBAAiB;;;;;EAKjB,WAAW;;;;EAIX;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA,eAAe;;;;;;;;;;;;;;;EAef,WAAW,OAAO;;KAGR;;;;EAIV;;;;EAIA,QAAQ,UAAU;;;;EAIlB,OAAO,MAAM;;;;EAIb;;;;;;;KAQU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCV;IACE;IACA;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BF;;;;;;;;;;;;;EAaA;;KAGU;;;;EAIV;;;;EAIA;;;;EAIA;;;;;;;;;;;;;EAaA,oBAAoB,OAAO;;;;;EAK3B,WAAW,OAAO;;;;EAIlB,iBAAiB;;;;EAIjB;IACE,SAAS,UAAU;;;;;;;;;EASrB;;;;;;;EAOA;;;;;;EAMA,WAAW;;;;;;;EAOX,eAAe;;;;cC5IJ,uCAAqB,0BAAA,6CAAA,cAAA;cA2HrB,yBAAwB,OAAA,OAAA,MAAA,eAKlC,8CAAyB,IAAA;cAYf,oCAAkB,0BAAA,0CAAA,cAAA;;;cCjOlB;EACX;EACA,gBAAgB;EAChB,UAAU;EACV;EAEY,cACV,gBACA,UACA,UACA,cACC;EAeH,kBAAiB,gBAAA,eAAA,OAAA,WAAA;IAOf;IACA;IACA;IACA;IACA;;;;;;;;;;;;EAmDF;;;;;;;;;;;;;;cCnFW;KAgBD,4BAA4B;;iBAexB,2BAA2B;iBAK3B,uBAAuB;;;;;;;;;;;;;;cCtB1B"}

package/dist/index.js

@@ -145,9 +145,14 @@ var LorikeetClient = class {
 //#endregion
 //#region src/errors.ts
 /**
-* Codes the chat page posts to the host as `{ type: 'error', error: CODE }`.
-* Mirrored here because the page publishes them nowhere else, so a host would
-* otherwise be matching on strings it discovered by observation.
+* The chat page's error vocabulary, as it reaches a host in
+* `{ type: 'error', error: CODE }`. Mirrored here because the page publishes it
+* nowhere else, so a host would otherwise be matching on strings it discovered
+* by observation.
+*
+* The page's own list rather than a list of codes seen in the wild:
+* `MISSING_PUBLIC_KEY` has no producer today, and is kept because narrowing this
+* would be a breaking change.
 */
 const LORIKEET_ERROR_CODES = [
 	"MISSING_TOKEN",