@skyporch/daykeeper-react-native 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -10,7 +10,12 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get widget-safe customer identity */
+        /**
+         * Get widget-safe customer identity
+         * @description API-only inbox gateways authenticate the customer token and return `409`
+         *     `{ "error": "widget_unavailable" }` before calling the conversation
+         *     provider. Use a widget-enabled tenant gateway for this operation.
+         */
         get: operations["getCustomerIdentity"];
         put?: never;
         post?: never;
@@ -113,6 +118,10 @@ interface paths {
          * Claim a signed-out widget conversation after sign-in
          * @description The widget token proves possession of the anonymous thread. The gateway
          *     refuses identified, foreign-tenant, or email-mismatched contacts.
+         *
+         *     API-only inbox gateways authenticate the token and return `409`
+         *     `{ "error": "widget_unavailable" }` before calling the conversation
+         *     provider. Use a widget-enabled tenant gateway for this operation.
          */
         post: operations["claimAnonymousConversation"];
         delete?: never;
@@ -190,7 +199,7 @@ interface components {
             status: "open" | "pending" | "resolved" | "snoozed";
             createdAt: number | string | null;
             updatedAt: number | string | null;
-            /** @description Chatwoot agent-side unread count; do not use for a customer badge. */
+            /** @description Agent-side unread count reported by the conversation provider; do not use for a customer badge. */
             unreadCount: number;
             /** @description Customer-side unread count used for product badges. */
             unreadForContact: number;
@@ -304,7 +313,24 @@ interface components {
             [key: string]: unknown;
         };
         CustomerError: {
+            /** @description Stable error code. Codes are extensible; handle unknown values safely. */
             error: string;
+            /** @description Optional customer-safe explanation, never infrastructure diagnostics. */
+            message?: string;
+            /**
+             * @description Optional server retry advice. False means do not automatically replay
+             *     this request, including a 429 usage ceiling. Absence preserves older
+             *     status-based handling. True does not guarantee a write is idempotent.
+             */
+            retryable?: boolean;
+            /**
+             * @description Optional next step. Known values are review_usage, review_setup and
+             *     refresh_conversation. Values are extensible and grant no authority
+             *     to change billing, budgets or account configuration.
+             */
+            nextAction?: string;
+        } & {
+            [key: string]: unknown;
         };
     };
     responses: {
@@ -317,6 +343,15 @@ interface components {
                 "application/json": components["schemas"]["CustomerError"];
             };
         };
+        /** @description API-only inbox gateways do not support widget identity or anonymous-conversation claims. */
+        WidgetUnavailable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["CustomerError"];
+            };
+        };
     };
     parameters: {
         ConversationId: number;
@@ -345,6 +380,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Error"];
+            409: components["responses"]["WidgetUnavailable"];
             default: components["responses"]["Error"];
         };
     };
@@ -516,6 +552,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Error"];
+            409: components["responses"]["WidgetUnavailable"];
             default: components["responses"]["Error"];
         };
     };
@@ -615,15 +652,19 @@ type DaykeeperClaimConversationResult = Schemas["ClaimConversationResult"];
 
 interface DaykeeperReactNativeTokenProviderContext {
     /**
-     * True only after Daykeeper rejected the first token with HTTP 401. The
+     * True only after a GET rejected the first token with HTTP 401 and did not
+     * explicitly forbid replay with retryable: false. The
      * provider should bypass any token cache and exchange the app session again.
      */
     forceRefresh: boolean;
+    /** Cancel credential exchange when the request is aborted or expires. */
+    signal?: AbortSignal;
 }
 type DaykeeperReactNativeTokenProvider = (context: DaykeeperReactNativeTokenProviderContext) => string | Promise<string>;
 interface DaykeeperReactNativeClientOptions {
     baseUrl: string;
     getAccessToken: DaykeeperReactNativeTokenProvider;
+    /** Must reject redirects, omit ambient cookies, and honor cache policy. */
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
 }
@@ -646,37 +687,57 @@ declare class DaykeeperReactNativeClient {
 }
 declare function createDaykeeperReactNativeClient(options: DaykeeperReactNativeClientOptions): DaykeeperReactNativeClient;
 
-type DaykeeperReactNativeTransportErrorCode = "INVALID_CONFIGURATION" | "NETWORK_ERROR" | "REQUEST_ABORTED" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "RESPONSE_TOO_LARGE";
+type DaykeeperReactNativeTransportErrorCode = "INVALID_CONFIGURATION" | "TOKEN_PROVIDER_ERROR" | "NETWORK_ERROR" | "REQUEST_ABORTED" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "RESPONSE_TOO_LARGE";
+/**
+ * Contract-documented next steps. The envelope is open and its values are
+ * extensible, so an unrecognized hint is dropped rather than surfaced: a
+ * gateway string is untrusted and none of these grant account authority.
+ *
+ * This is deliberately narrower than the error-code rule above. A code is only
+ * ever compared by the app, so an unknown one is inert; a next action is a UI
+ * instruction the app acts on, so only the three the contract defines are
+ * allowed through.
+ */
+type DaykeeperReactNativeNextAction = "review_usage" | "review_setup" | "refresh_conversation";
 declare class DaykeeperReactNativeApiError extends Error {
     readonly status: number;
     readonly code: string;
     readonly retryable: boolean;
+    readonly outcomeUnknown: boolean;
+    readonly nextAction?: DaykeeperReactNativeNextAction;
     constructor(options: {
         status: number;
-        code: string;
-        retryable: boolean;
+        code?: unknown;
+        nextAction?: unknown;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
     });
     toJSON(): {
         name: string;
         status: number;
         code: string;
         retryable: boolean;
+        outcomeUnknown: boolean;
+        nextAction?: DaykeeperReactNativeNextAction;
     };
 }
 declare class DaykeeperReactNativeTransportError extends Error {
     readonly code: DaykeeperReactNativeTransportErrorCode;
     readonly retryable: boolean;
+    readonly outcomeUnknown: boolean;
     constructor(options: {
         code: DaykeeperReactNativeTransportErrorCode;
         message: string;
         retryable?: boolean;
+        outcomeUnknown?: boolean;
     });
     toJSON(): {
         name: string;
         code: DaykeeperReactNativeTransportErrorCode;
         message: string;
         retryable: boolean;
+        outcomeUnknown: boolean;
     };
 }
 
-export { type DaykeeperAttachment, type DaykeeperClaimConversationResult, type DaykeeperConversation, type DaykeeperConversationList, type DaykeeperConversationResult, type DaykeeperCustomerIdentity, type components as DaykeeperCustomerOpenApiComponents, type operations as DaykeeperCustomerOpenApiOperations, type paths as DaykeeperCustomerOpenApiPaths, type DaykeeperMessage, type DaykeeperMessageList, type DaykeeperMessageResult, type DaykeeperMessageSender, DaykeeperReactNativeApiError, DaykeeperReactNativeClient, type DaykeeperReactNativeClientOptions, type DaykeeperReactNativeRequestOptions, type DaykeeperReactNativeTokenProvider, type DaykeeperReactNativeTokenProviderContext, DaykeeperReactNativeTransportError, type DaykeeperReactNativeTransportErrorCode, type DaykeeperSeenResult, type DaykeeperUnreadSummary, createDaykeeperReactNativeClient };
+export { type DaykeeperAttachment, type DaykeeperClaimConversationResult, type DaykeeperConversation, type DaykeeperConversationList, type DaykeeperConversationResult, type DaykeeperCustomerIdentity, type components as DaykeeperCustomerOpenApiComponents, type operations as DaykeeperCustomerOpenApiOperations, type paths as DaykeeperCustomerOpenApiPaths, type DaykeeperMessage, type DaykeeperMessageList, type DaykeeperMessageResult, type DaykeeperMessageSender, DaykeeperReactNativeApiError, DaykeeperReactNativeClient, type DaykeeperReactNativeClientOptions, type DaykeeperReactNativeNextAction, type DaykeeperReactNativeRequestOptions, type DaykeeperReactNativeTokenProvider, type DaykeeperReactNativeTokenProviderContext, DaykeeperReactNativeTransportError, type DaykeeperReactNativeTransportErrorCode, type DaykeeperSeenResult, type DaykeeperUnreadSummary, createDaykeeperReactNativeClient };

package/dist/index.d.ts

@@ -10,7 +10,12 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get widget-safe customer identity */
+        /**
+         * Get widget-safe customer identity
+         * @description API-only inbox gateways authenticate the customer token and return `409`
+         *     `{ "error": "widget_unavailable" }` before calling the conversation
+         *     provider. Use a widget-enabled tenant gateway for this operation.
+         */
         get: operations["getCustomerIdentity"];
         put?: never;
         post?: never;
@@ -113,6 +118,10 @@ interface paths {
          * Claim a signed-out widget conversation after sign-in
          * @description The widget token proves possession of the anonymous thread. The gateway
          *     refuses identified, foreign-tenant, or email-mismatched contacts.
+         *
+         *     API-only inbox gateways authenticate the token and return `409`
+         *     `{ "error": "widget_unavailable" }` before calling the conversation
+         *     provider. Use a widget-enabled tenant gateway for this operation.
          */
         post: operations["claimAnonymousConversation"];
         delete?: never;
@@ -190,7 +199,7 @@ interface components {
             status: "open" | "pending" | "resolved" | "snoozed";
             createdAt: number | string | null;
             updatedAt: number | string | null;
-            /** @description Chatwoot agent-side unread count; do not use for a customer badge. */
+            /** @description Agent-side unread count reported by the conversation provider; do not use for a customer badge. */
             unreadCount: number;
             /** @description Customer-side unread count used for product badges. */
             unreadForContact: number;
@@ -304,7 +313,24 @@ interface components {
             [key: string]: unknown;
         };
         CustomerError: {
+            /** @description Stable error code. Codes are extensible; handle unknown values safely. */
             error: string;
+            /** @description Optional customer-safe explanation, never infrastructure diagnostics. */
+            message?: string;
+            /**
+             * @description Optional server retry advice. False means do not automatically replay
+             *     this request, including a 429 usage ceiling. Absence preserves older
+             *     status-based handling. True does not guarantee a write is idempotent.
+             */
+            retryable?: boolean;
+            /**
+             * @description Optional next step. Known values are review_usage, review_setup and
+             *     refresh_conversation. Values are extensible and grant no authority
+             *     to change billing, budgets or account configuration.
+             */
+            nextAction?: string;
+        } & {
+            [key: string]: unknown;
         };
     };
     responses: {
@@ -317,6 +343,15 @@ interface components {
                 "application/json": components["schemas"]["CustomerError"];
             };
         };
+        /** @description API-only inbox gateways do not support widget identity or anonymous-conversation claims. */
+        WidgetUnavailable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["CustomerError"];
+            };
+        };
     };
     parameters: {
         ConversationId: number;
@@ -345,6 +380,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Error"];
+            409: components["responses"]["WidgetUnavailable"];
             default: components["responses"]["Error"];
         };
     };
@@ -516,6 +552,7 @@ interface operations {
                 };
             };
             401: components["responses"]["Error"];
+            409: components["responses"]["WidgetUnavailable"];
             default: components["responses"]["Error"];
         };
     };
@@ -615,15 +652,19 @@ type DaykeeperClaimConversationResult = Schemas["ClaimConversationResult"];
 
 interface DaykeeperReactNativeTokenProviderContext {
     /**
-     * True only after Daykeeper rejected the first token with HTTP 401. The
+     * True only after a GET rejected the first token with HTTP 401 and did not
+     * explicitly forbid replay with retryable: false. The
      * provider should bypass any token cache and exchange the app session again.
      */
     forceRefresh: boolean;
+    /** Cancel credential exchange when the request is aborted or expires. */
+    signal?: AbortSignal;
 }
 type DaykeeperReactNativeTokenProvider = (context: DaykeeperReactNativeTokenProviderContext) => string | Promise<string>;
 interface DaykeeperReactNativeClientOptions {
     baseUrl: string;
     getAccessToken: DaykeeperReactNativeTokenProvider;
+    /** Must reject redirects, omit ambient cookies, and honor cache policy. */
     fetch?: typeof globalThis.fetch;
     timeoutMs?: number;
 }
@@ -646,37 +687,57 @@ declare class DaykeeperReactNativeClient {
 }
 declare function createDaykeeperReactNativeClient(options: DaykeeperReactNativeClientOptions): DaykeeperReactNativeClient;
 
-type DaykeeperReactNativeTransportErrorCode = "INVALID_CONFIGURATION" | "NETWORK_ERROR" | "REQUEST_ABORTED" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "RESPONSE_TOO_LARGE";
+type DaykeeperReactNativeTransportErrorCode = "INVALID_CONFIGURATION" | "TOKEN_PROVIDER_ERROR" | "NETWORK_ERROR" | "REQUEST_ABORTED" | "REQUEST_TIMEOUT" | "INVALID_RESPONSE" | "RESPONSE_TOO_LARGE";
+/**
+ * Contract-documented next steps. The envelope is open and its values are
+ * extensible, so an unrecognized hint is dropped rather than surfaced: a
+ * gateway string is untrusted and none of these grant account authority.
+ *
+ * This is deliberately narrower than the error-code rule above. A code is only
+ * ever compared by the app, so an unknown one is inert; a next action is a UI
+ * instruction the app acts on, so only the three the contract defines are
+ * allowed through.
+ */
+type DaykeeperReactNativeNextAction = "review_usage" | "review_setup" | "refresh_conversation";
 declare class DaykeeperReactNativeApiError extends Error {
     readonly status: number;
     readonly code: string;
     readonly retryable: boolean;
+    readonly outcomeUnknown: boolean;
+    readonly nextAction?: DaykeeperReactNativeNextAction;
     constructor(options: {
         status: number;
-        code: string;
-        retryable: boolean;
+        code?: unknown;
+        nextAction?: unknown;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
     });
     toJSON(): {
         name: string;
         status: number;
         code: string;
         retryable: boolean;
+        outcomeUnknown: boolean;
+        nextAction?: DaykeeperReactNativeNextAction;
     };
 }
 declare class DaykeeperReactNativeTransportError extends Error {
     readonly code: DaykeeperReactNativeTransportErrorCode;
     readonly retryable: boolean;
+    readonly outcomeUnknown: boolean;
     constructor(options: {
         code: DaykeeperReactNativeTransportErrorCode;
         message: string;
         retryable?: boolean;
+        outcomeUnknown?: boolean;
     });
     toJSON(): {
         name: string;
         code: DaykeeperReactNativeTransportErrorCode;
         message: string;
         retryable: boolean;
+        outcomeUnknown: boolean;
     };
 }
 
-export { type DaykeeperAttachment, type DaykeeperClaimConversationResult, type DaykeeperConversation, type DaykeeperConversationList, type DaykeeperConversationResult, type DaykeeperCustomerIdentity, type components as DaykeeperCustomerOpenApiComponents, type operations as DaykeeperCustomerOpenApiOperations, type paths as DaykeeperCustomerOpenApiPaths, type DaykeeperMessage, type DaykeeperMessageList, type DaykeeperMessageResult, type DaykeeperMessageSender, DaykeeperReactNativeApiError, DaykeeperReactNativeClient, type DaykeeperReactNativeClientOptions, type DaykeeperReactNativeRequestOptions, type DaykeeperReactNativeTokenProvider, type DaykeeperReactNativeTokenProviderContext, DaykeeperReactNativeTransportError, type DaykeeperReactNativeTransportErrorCode, type DaykeeperSeenResult, type DaykeeperUnreadSummary, createDaykeeperReactNativeClient };
+export { type DaykeeperAttachment, type DaykeeperClaimConversationResult, type DaykeeperConversation, type DaykeeperConversationList, type DaykeeperConversationResult, type DaykeeperCustomerIdentity, type components as DaykeeperCustomerOpenApiComponents, type operations as DaykeeperCustomerOpenApiOperations, type paths as DaykeeperCustomerOpenApiPaths, type DaykeeperMessage, type DaykeeperMessageList, type DaykeeperMessageResult, type DaykeeperMessageSender, DaykeeperReactNativeApiError, DaykeeperReactNativeClient, type DaykeeperReactNativeClientOptions, type DaykeeperReactNativeNextAction, type DaykeeperReactNativeRequestOptions, type DaykeeperReactNativeTokenProvider, type DaykeeperReactNativeTokenProviderContext, DaykeeperReactNativeTransportError, type DaykeeperReactNativeTransportErrorCode, type DaykeeperSeenResult, type DaykeeperUnreadSummary, createDaykeeperReactNativeClient };