@talqui-oss/talqui-sdk-reactnative 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENT_INSTRUCTIONS.md +182 -0
- package/LICENSE.md +21 -0
- package/README.md +280 -2
- package/dist/index.d.mts +150 -0
- package/dist/index.d.ts +150 -0
- package/dist/index.js +613 -0
- package/dist/index.mjs +581 -0
- package/package.json +83 -4
- package/src/TalquiChat.tsx +40 -0
- package/src/TalquiProvider.tsx +509 -0
- package/src/TalquiWebView.tsx +153 -0
- package/src/identity.ts +40 -0
- package/src/index.ts +13 -0
- package/src/protocol.ts +101 -0
- package/src/types.ts +70 -0
package/src/identity.ts
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import AsyncStorage from '@react-native-async-storage/async-storage';
|
|
2
|
+
|
|
3
|
+
import { IDENTITY_PATTERN, type Identity } from './protocol';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The visitor identity lives here, in the app's storage — never in the
|
|
7
|
+
* WebView's. The chat page persists nothing about the visitor; it receives
|
|
8
|
+
* the identity in its URL on every load. So `logout()` deleting this one key
|
|
9
|
+
* is enough for the next user of the phone to start from nothing.
|
|
10
|
+
*/
|
|
11
|
+
const key = (tenantId: string) => `talqui:identity:${tenantId}`;
|
|
12
|
+
|
|
13
|
+
export async function readIdentity(tenantId: string): Promise<Identity | null> {
|
|
14
|
+
try {
|
|
15
|
+
const raw = await AsyncStorage.getItem(key(tenantId));
|
|
16
|
+
const parsed = raw ? (JSON.parse(raw) as Identity) : null;
|
|
17
|
+
if (parsed && (parsed.kind === 'anonymous' || parsed.kind === 'identified') && IDENTITY_PATTERN.test(parsed.id)) {
|
|
18
|
+
return parsed;
|
|
19
|
+
}
|
|
20
|
+
} catch {
|
|
21
|
+
// Unreadable storage: start as a new anonymous visitor.
|
|
22
|
+
}
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export async function writeIdentity(tenantId: string, identity: Identity): Promise<void> {
|
|
27
|
+
try {
|
|
28
|
+
await AsyncStorage.setItem(key(tenantId), JSON.stringify(identity));
|
|
29
|
+
} catch {
|
|
30
|
+
// The chat still works; the visitor just starts anew on the next app launch.
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export async function clearIdentity(tenantId: string): Promise<void> {
|
|
35
|
+
try {
|
|
36
|
+
await AsyncStorage.removeItem(key(tenantId));
|
|
37
|
+
} catch {
|
|
38
|
+
// Nothing more can be done; the page itself keeps nothing.
|
|
39
|
+
}
|
|
40
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export { TalquiProvider, useTalqui, useTalquiEvent } from './TalquiProvider';
|
|
2
|
+
export type { TalquiProviderProps } from './TalquiProvider';
|
|
3
|
+
export { TalquiChat } from './TalquiChat';
|
|
4
|
+
export type { TalquiChatProps } from './TalquiChat';
|
|
5
|
+
export type {
|
|
6
|
+
TalquiApi,
|
|
7
|
+
TalquiContact,
|
|
8
|
+
TalquiEventListener,
|
|
9
|
+
TalquiEventMap,
|
|
10
|
+
TalquiEventName,
|
|
11
|
+
TalquiMeta,
|
|
12
|
+
TalquiUser,
|
|
13
|
+
} from './types';
|
package/src/protocol.ts
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import type { TalquiEventMap, TalquiEventName, TalquiMeta } from './types';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* talqui.bridge.v1: the messages exchanged with the chat page running in the
|
|
5
|
+
* WebView. Commands go in through `window.TalquiBridge.receive(json)`, events
|
|
6
|
+
* come out through `window.ReactNativeWebView.postMessage(json)`.
|
|
7
|
+
*/
|
|
8
|
+
export const PROTOCOL = 1;
|
|
9
|
+
export const DEFAULT_BASE_URL = 'https://webchat.talqui.chat';
|
|
10
|
+
export const SDK_LABEL = 'react-native@0.1.1';
|
|
11
|
+
|
|
12
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
|
|
13
|
+
export const IDENTITY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
|
|
14
|
+
export const USER_HASH_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
|
|
15
|
+
const META_KEY = /^[a-z0-9_-]{1,60}$/;
|
|
16
|
+
const UNSAFE_KEYS = ['__proto__', 'constructor', 'prototype'];
|
|
17
|
+
|
|
18
|
+
export type Identity = { kind: 'anonymous' | 'identified'; id: string };
|
|
19
|
+
|
|
20
|
+
export function isUuid(value: string): boolean {
|
|
21
|
+
return UUID.test(value);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The page to load. Everything lives in the URL fragment (after `#`), which
|
|
26
|
+
* is never sent to a server, so the identity never reaches access logs.
|
|
27
|
+
*/
|
|
28
|
+
export function buildChatUrl(options: {
|
|
29
|
+
baseUrl: string;
|
|
30
|
+
tenantId: string;
|
|
31
|
+
connectionId: string;
|
|
32
|
+
identity: Identity | null;
|
|
33
|
+
}): string {
|
|
34
|
+
const query = new URLSearchParams({
|
|
35
|
+
T_ID: options.tenantId,
|
|
36
|
+
PC_ID: options.connectionId,
|
|
37
|
+
EMBED: '1',
|
|
38
|
+
SDK: SDK_LABEL,
|
|
39
|
+
});
|
|
40
|
+
if (options.identity) {
|
|
41
|
+
query.set(options.identity.kind === 'identified' ? 'S_ID' : 'A_ID', options.identity.id);
|
|
42
|
+
}
|
|
43
|
+
return `${options.baseUrl.replace(/\/+$/, '')}/#/chat?${query.toString()}`;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The JavaScript injected into the WebView to deliver one command. */
|
|
47
|
+
export function commandScript(name: string, payload: object, id: string): string {
|
|
48
|
+
const json = JSON.stringify({ talqui: PROTOCOL, kind: 'command', name, id, payload });
|
|
49
|
+
// The JSON is passed as a string literal, so nothing in it is evaluated as code.
|
|
50
|
+
return `window.TalquiBridge&&window.TalquiBridge.receive(${JSON.stringify(json)});true;`;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export type ParsedEvent = { [E in TalquiEventName]: { name: E; payload: TalquiEventMap[E] } }[TalquiEventName];
|
|
54
|
+
|
|
55
|
+
/** Reads an event posted by the page; `null` for anything that is not a v1 event. */
|
|
56
|
+
export function parseEvent(raw: string): ParsedEvent | null {
|
|
57
|
+
let message: unknown;
|
|
58
|
+
try {
|
|
59
|
+
message = JSON.parse(raw);
|
|
60
|
+
} catch {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
if (typeof message !== 'object' || message === null) return null;
|
|
64
|
+
const { talqui, kind, name, payload } = message as Record<string, unknown>;
|
|
65
|
+
if (talqui !== PROTOCOL || kind !== 'event' || typeof name !== 'string') return null;
|
|
66
|
+
return { name, payload: typeof payload === 'object' && payload !== null ? payload : {} } as ParsedEvent;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Turns what the app passed into what the chat accepts: keys lowercased,
|
|
71
|
+
* numbers and booleans as text, long values cut. Anything that cannot be
|
|
72
|
+
* fixed is dropped with a warning — never an exception in the host app.
|
|
73
|
+
*/
|
|
74
|
+
export function normalizeMeta(meta: TalquiMeta, warn: (message: string) => void): Record<string, string | null> {
|
|
75
|
+
const out: Record<string, string | null> = {};
|
|
76
|
+
if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) {
|
|
77
|
+
warn('metadata must be an object of key/value pairs; ignored.');
|
|
78
|
+
return out;
|
|
79
|
+
}
|
|
80
|
+
for (const rawKey of Object.getOwnPropertyNames(meta)) {
|
|
81
|
+
const key = rawKey.trim().toLowerCase().replace(/\s+/g, '_');
|
|
82
|
+
if (key !== rawKey) warn(`metadata key "${rawKey}" was sent as "${key}".`);
|
|
83
|
+
if (!META_KEY.test(key) || UNSAFE_KEYS.includes(key)) {
|
|
84
|
+
warn(`metadata key "${rawKey}" ignored: use lowercase letters, digits, "_" and "-" (max 60 chars).`);
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
const value = (meta as Record<string, unknown>)[rawKey];
|
|
88
|
+
if (value === null) {
|
|
89
|
+
out[key] = null;
|
|
90
|
+
} else if (typeof value === 'string') {
|
|
91
|
+
out[key] = value.trim().slice(0, 255);
|
|
92
|
+
} else if (typeof value === 'number' && Number.isFinite(value)) {
|
|
93
|
+
out[key] = String(value);
|
|
94
|
+
} else if (typeof value === 'boolean') {
|
|
95
|
+
out[key] = String(value);
|
|
96
|
+
} else {
|
|
97
|
+
warn(`metadata "${rawKey}" ignored: values are strings, numbers, booleans or null.`);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return out;
|
|
101
|
+
}
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/** Who the visitor is, as far as your app knows. Every field is optional. */
|
|
2
|
+
export interface TalquiUser {
|
|
3
|
+
/** Your own id for the user. Only used for your bookkeeping; never sent as the identity. */
|
|
4
|
+
userId?: string;
|
|
5
|
+
/**
|
|
6
|
+
* Identifies the user across devices and keeps their history after they
|
|
7
|
+
* log in again. Computed on YOUR backend, never in the app:
|
|
8
|
+
* `HMAC_SHA256(secret, "<tenantId>:<userId>")` as lowercase hex.
|
|
9
|
+
* Anyone holding it can read that user's conversation, so treat it like a
|
|
10
|
+
* session token. 32 to 128 chars of `A-Z a-z 0-9 _ -`.
|
|
11
|
+
*/
|
|
12
|
+
userHash?: string;
|
|
13
|
+
name?: string;
|
|
14
|
+
email?: string;
|
|
15
|
+
phone?: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface TalquiContact {
|
|
19
|
+
name?: string;
|
|
20
|
+
email?: string;
|
|
21
|
+
phone?: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Custom data: strings, numbers or booleans (stored as text). `null` removes a key. */
|
|
25
|
+
export type TalquiMeta = Record<string, string | number | boolean | null>;
|
|
26
|
+
|
|
27
|
+
export interface TalquiEventMap {
|
|
28
|
+
ready: { protocol: number; webchatVersion: string; identity: { kind: 'anonymous' | 'identified'; anonymousId?: string } };
|
|
29
|
+
sessionStarted: { sessionId: string | null };
|
|
30
|
+
messageSent: { messageId: string; type: string };
|
|
31
|
+
messageReceived: { messageId: string; type: string; preview: string; operatorName: string | null };
|
|
32
|
+
unreadChanged: { count: number };
|
|
33
|
+
closeRequested: Record<string, never>;
|
|
34
|
+
openUrl: { url: string };
|
|
35
|
+
resetDone: Record<string, never>;
|
|
36
|
+
error: { code: string; message: string; commandId?: string };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export type TalquiEventName = keyof TalquiEventMap;
|
|
40
|
+
|
|
41
|
+
export type TalquiEventListener<E extends TalquiEventName> = (payload: TalquiEventMap[E]) => void;
|
|
42
|
+
|
|
43
|
+
export interface TalquiApi {
|
|
44
|
+
/** Shows the chat full screen. */
|
|
45
|
+
open(): void;
|
|
46
|
+
/** Hides the full-screen chat. The conversation keeps running in the background. */
|
|
47
|
+
close(): void;
|
|
48
|
+
/** Mounts the chat ahead of time (hidden), so `open()` is instant and unread messages are counted. */
|
|
49
|
+
preload(): void;
|
|
50
|
+
/**
|
|
51
|
+
* Sets who the user is. With a `userHash` the chat reloads as that user
|
|
52
|
+
* (their history follows them across devices); without one, the details
|
|
53
|
+
* are attached to this device's anonymous visitor.
|
|
54
|
+
*/
|
|
55
|
+
identify(user: TalquiUser): Promise<void>;
|
|
56
|
+
setContact(contact: TalquiContact): void;
|
|
57
|
+
/** Data about the person, kept on their contact. */
|
|
58
|
+
setContactMeta(meta: TalquiMeta): void;
|
|
59
|
+
/** Data about this conversation (an order, the screen they are on). Can change at any moment. */
|
|
60
|
+
setSessionMeta(meta: TalquiMeta): void;
|
|
61
|
+
/** Puts text in the message box. The user still decides to send it. */
|
|
62
|
+
prefill(text: string): void;
|
|
63
|
+
/** Call it when your user logs out: forgets this user and starts a fresh anonymous visitor. */
|
|
64
|
+
logout(): Promise<void>;
|
|
65
|
+
/** Messages received while the chat was not on screen. */
|
|
66
|
+
unreadCount: number;
|
|
67
|
+
/** Whether the chat is loaded and accepting commands. */
|
|
68
|
+
isReady: boolean;
|
|
69
|
+
isOpen: boolean;
|
|
70
|
+
}
|