@bigbinary/neeto-assist-frontend 1.2.1 → 1.3.0-beta1
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/README.md +430 -21
- package/app/javascript/src/translations/en.json +39 -2
- package/dist/.ready +1 -1
- package/dist/NeetoAssistButton.js +13 -6
- package/dist/NeetoAssistButton.js.map +1 -1
- package/dist/NeetoAssistPane.js +1469 -166
- package/dist/NeetoAssistPane.js.map +1 -1
- package/dist/cjs/NeetoAssistButton.js +16 -9
- package/dist/cjs/NeetoAssistButton.js.map +1 -1
- package/dist/cjs/NeetoAssistPane.js +1491 -188
- package/dist/cjs/NeetoAssistPane.js.map +1 -1
- package/dist/cjs/index.js +11 -5
- package/dist/cjs/index.js.map +1 -1
- package/dist/cjs/useNeetoAssistAssistant.js +43 -0
- package/dist/cjs/useNeetoAssistAssistant.js.map +1 -0
- package/dist/cjs/useNeetoAssistStatus.js +3 -1
- package/dist/cjs/useNeetoAssistStatus.js.map +1 -1
- package/dist/index.js +10 -5
- package/dist/index.js.map +1 -1
- package/dist/neeto_assist-COp7BR77.js +249 -0
- package/dist/neeto_assist-COp7BR77.js.map +1 -0
- package/dist/neeto_assist-D1wzZ3ou.js +219 -0
- package/dist/neeto_assist-D1wzZ3ou.js.map +1 -0
- package/dist/useNeetoAssistAssistant.js +41 -0
- package/dist/useNeetoAssistAssistant.js.map +1 -0
- package/dist/useNeetoAssistStatus.js +3 -1
- package/dist/useNeetoAssistStatus.js.map +1 -1
- package/dist/useNeetoAssistStore-Bj6niQdc.js +103 -0
- package/dist/useNeetoAssistStore-Bj6niQdc.js.map +1 -0
- package/dist/useNeetoAssistStore-Dgt8aV52.js +101 -0
- package/dist/useNeetoAssistStore-Dgt8aV52.js.map +1 -0
- package/dist/{useNeetoAssistStore-InICsbe8.js → useRunsApi-BgsICthX.js} +228 -113
- package/dist/useRunsApi-BgsICthX.js.map +1 -0
- package/dist/{useNeetoAssistStore-VaZp3268.js → useRunsApi-Rh6xXOwm.js} +232 -112
- package/dist/useRunsApi-Rh6xXOwm.js.map +1 -0
- package/package.json +4 -4
- package/types.d.ts +81 -8
- package/dist/neeto_assist-CpUBA-3Z.js +0 -135
- package/dist/neeto_assist-CpUBA-3Z.js.map +0 -1
- package/dist/neeto_assist-CznTN_YY.js +0 -157
- package/dist/neeto_assist-CznTN_YY.js.map +0 -1
- package/dist/useNeetoAssistStore-InICsbe8.js.map +0 -1
- package/dist/useNeetoAssistStore-VaZp3268.js.map +0 -1
package/README.md
CHANGED
|
@@ -20,6 +20,7 @@ something up in the host for a rep.
|
|
|
20
20
|
- [Host adapter](#host-adapter)
|
|
21
21
|
- [Asking for a reply suggestion](#asking-for-a-reply-suggestion)
|
|
22
22
|
- [Lookups and actions](#lookups-and-actions)
|
|
23
|
+
- [The assistant and product lookups](#the-assistant-and-product-lookups)
|
|
23
24
|
- [The grant, and what a host trusts](#the-grant-and-what-a-host-trusts)
|
|
24
25
|
- [Endpoints](#endpoints)
|
|
25
26
|
2. [Frontend package](#frontend-package)
|
|
@@ -80,9 +81,17 @@ NeetoAssistEngine.configure do |config|
|
|
|
80
81
|
# Optional, in seconds. How long a click on one of NeetoAssist's own actions
|
|
81
82
|
# waits for NeetoAssist to run it. This is the default.
|
|
82
83
|
config.own_action_read_timeout = 20
|
|
84
|
+
# Optional, in seconds. How long one of the product's own lookups may run
|
|
85
|
+
# before the engine stops it and tells NeetoAssist it failed. This is the
|
|
86
|
+
# default.
|
|
87
|
+
config.product_lookup_timeout = 20
|
|
83
88
|
# Optional. How long NeetoAssist may look things up as the rep who asked.
|
|
84
89
|
# 15 minutes is the default and the most: a host can only shorten it.
|
|
85
90
|
config.grant_ttl = 15.minutes
|
|
91
|
+
# Only for a product that shares its lookups with people who ask NeetoAssist
|
|
92
|
+
# in another Neeto product: NeetoAssist's public key for passes (Ed25519,
|
|
93
|
+
# PEM). Line breaks written as the two characters \n are read as line breaks.
|
|
94
|
+
config.pass_public_key = ENV["NEETO_ASSIST_PASS_PUBLIC_KEY"]
|
|
86
95
|
end
|
|
87
96
|
```
|
|
88
97
|
|
|
@@ -107,8 +116,8 @@ subclass of `NeetoAssistEngine::HostAdapter`:
|
|
|
107
116
|
| Method | Returns |
|
|
108
117
|
| --- | --- |
|
|
109
118
|
| `enabled?(organization)` | Whether NeetoAssist is on for the workspace: the host's rollout gate, such as a Flipper flag on `Organization`. |
|
|
110
|
-
| `find_conversation(organization, conversation_id)` | The conversation with that id in that workspace, or `nil`. |
|
|
111
|
-
| `can_use?(user, conversation)` | Whether this rep may see NeetoAssist on the conversation. |
|
|
119
|
+
| `find_conversation(organization, conversation_id)` | The conversation with that id in that workspace, or `nil`. Defaults to `nil`, for a product that offers only the assistant. |
|
|
120
|
+
| `can_use?(user, conversation)` | Whether this rep may see NeetoAssist on the conversation. Defaults to `false`. |
|
|
112
121
|
| `can_buy_credits?(user)` | Whether this rep may buy NeetoAssist credits, such as a workspace admin. Defaults to `false`. Only they get the link to buy more once the workspace runs out. |
|
|
113
122
|
| `conversation_payload(conversation)` | The conversation as NeetoAssist takes it (below), built when it is sent. |
|
|
114
123
|
| `conversation_external_id(conversation)` | The conversation's id in NeetoAssist. Defaults to `conversation.id.to_s`. |
|
|
@@ -117,6 +126,14 @@ subclass of `NeetoAssistEngine::HostAdapter`:
|
|
|
117
126
|
| `actions(user, conversation)` | The `NeetoAssistEngine::Action` classes NeetoAssist may suggest to this rep. Defaults to `[]`. |
|
|
118
127
|
| `find_user(organization, user_id)` | The workspace's person with that id, or `nil`. Defaults to `organization.users.find_by(id: user_id)`. The engine finds the rep again with it for every lookup. |
|
|
119
128
|
| `user_role(user)` | The rep's role in a word or two, such as "Admin". Defaults to `nil`. NeetoAssist is told who it is talking to. |
|
|
129
|
+
| `user_time_zone(user)` | The person's time zone, an IANA name such as "Asia/Kolkata" or one of Rails' zone names. Defaults to `user.try(:time_zone)`. NeetoAssist reads "tomorrow" in it. |
|
|
130
|
+
| `product_lookups(user, conversation)` | The product's own MCP read tools NeetoAssist may use as this person ([below](#the-assistant-and-product-lookups)). Defaults to `ProductLookups.none`. `conversation` is `nil` in the assistant. |
|
|
131
|
+
| `shared_lookups(user)` | The product's own MCP read tools for a person who is asking NeetoAssist in another Neeto product ([below](#shared-lookups-for-a-person-asking-in-another-product)). Defaults to `ProductLookups.none`. |
|
|
132
|
+
| `find_user_by_guid(organization, guid)` | The workspace's person with that NeetoAuth guid, in lower case, or `nil`. Defaults to `organization.users.find_by(guid:)`. |
|
|
133
|
+
| `assistant?(user)` | Whether this person may open NeetoAssist as their own assistant. Defaults to `false`. |
|
|
134
|
+
| `assistant_context(user, page)` | What the person is looking at in the assistant, from `page` (`{ "path" => ..., "title" => ... }`, from the browser). Defaults to `{}`. |
|
|
135
|
+
| `assistant_tools(user)` | The Tool classes NeetoAssist may look things up with in the assistant, built with `conversation: nil`. Defaults to `[]`. |
|
|
136
|
+
| `assistant_suggestions(user)` | The first questions the pane offers on an empty thread, at most six short sentences. Defaults to `[]`. |
|
|
120
137
|
|
|
121
138
|
```ruby
|
|
122
139
|
module NeetoAssist
|
|
@@ -165,8 +182,13 @@ end
|
|
|
165
182
|
each with `id`, `author` (`visitor`, `agent` or `bot`), `author_name`, `body` (plain text, at most 4,000 characters)
|
|
166
183
|
and `created_at`. Leave private notes out.
|
|
167
184
|
|
|
168
|
-
If `context`, `tools`, `actions` or `
|
|
169
|
-
part, and the error goes to Honeybadger.
|
|
185
|
+
If `context`, `tools`, `actions`, `product_lookups`, `user_role` or `user_time_zone` raises, the rep's question still
|
|
186
|
+
goes to NeetoAssist, without that part, and the error goes to Honeybadger.
|
|
187
|
+
|
|
188
|
+
A host that has conversations and no assistant, such as NeetoChat, overrides none of the assistant methods and
|
|
189
|
+
`product_lookups`, and nothing changes for it. With every question the engine also tells NeetoAssist the asker's
|
|
190
|
+
NeetoAuth `guid`, when the user has one, and their `time_zone`. A host that shares nothing overrides neither
|
|
191
|
+
`shared_lookups` nor `find_user_by_guid` and sets no `pass_public_key`.
|
|
170
192
|
|
|
171
193
|
### Asking for a reply suggestion
|
|
172
194
|
|
|
@@ -241,6 +263,8 @@ end
|
|
|
241
263
|
nothing and goes to Honeybadger.
|
|
242
264
|
- `summary(result)` is a few words about the result for the pane, such as "3 people". The rep reads them, so
|
|
243
265
|
translate them as the host translates its own screens ([below](#the-language-of-a-lookup-and-a-card)).
|
|
266
|
+
- `sources(result)` names the records of the result a person can be pointed to, so an answer built on one can
|
|
267
|
+
show it under the answer as a link ([below](#a-tool-that-names-its-sources)). None by default.
|
|
244
268
|
- `available?` says whether this rep may use the tool on this conversation. NeetoAssist is never told about a tool
|
|
245
269
|
that is not available, and cannot call it.
|
|
246
270
|
|
|
@@ -251,7 +275,70 @@ A tool has `organization`, `user` (the rep who asked) and `conversation`. Three
|
|
|
251
275
|
finder the host's screens use.
|
|
252
276
|
2. **Only read.** The engine runs a lookup with writes to the database refused, so a tool that tries to change
|
|
253
277
|
something raises `ActiveRecord::ReadOnlyError`. A change is an action.
|
|
254
|
-
3. **Be quick.** NeetoAssist waits 8 seconds for a lookup
|
|
278
|
+
3. **Be quick.** NeetoAssist waits 8 seconds for a lookup on a conversation and 25 in the assistant, and less when
|
|
279
|
+
its answer is nearly out of time.
|
|
280
|
+
|
|
281
|
+
#### A tool that names its sources
|
|
282
|
+
|
|
283
|
+
An answer lists what it rests on under it. A tool that returns records with pages of their own, such as earlier
|
|
284
|
+
conversations, names each of them in `sources`, and the answer can then say "in the conversation of 3 November
|
|
285
|
+
about the refund" and link to it. A tool that names none is listed by itself, with its label and summary.
|
|
286
|
+
|
|
287
|
+
```ruby
|
|
288
|
+
module NeetoAssist
|
|
289
|
+
module Tools
|
|
290
|
+
class SearchConversations < NeetoAssistEngine::Tool
|
|
291
|
+
description "Finds the customer's earlier conversations by words in them, newest first, at most 10."
|
|
292
|
+
label "Searching earlier conversations"
|
|
293
|
+
param :query, :string, description: "Words to look for."
|
|
294
|
+
|
|
295
|
+
def call(query:)
|
|
296
|
+
ConversationPolicy::Scope.new(user, organization.conversations).resolve.search(query).limit(10).map do |found|
|
|
297
|
+
{ id: found.id, contact: found.contact.name, started_at: found.created_at.iso8601 }
|
|
298
|
+
end
|
|
299
|
+
end
|
|
300
|
+
|
|
301
|
+
def sources(result)
|
|
302
|
+
result.map do |found|
|
|
303
|
+
title = I18n.t(
|
|
304
|
+
"neeto_assist.sources.conversation", name: found[:contact],
|
|
305
|
+
date: I18n.l(Time.zone.parse(found[:started_at]).to_date, format: :long))
|
|
306
|
+
{
|
|
307
|
+
kind: "conversation",
|
|
308
|
+
id: found[:id],
|
|
309
|
+
title: title.truncate(NeetoAssistEngine::Sources::MAX_TITLE_LENGTH),
|
|
310
|
+
url: Rails.application.routes.url_helpers.admin_conversation_url(found[:id], subdomain: organization.subdomain)
|
|
311
|
+
}
|
|
312
|
+
end
|
|
313
|
+
end
|
|
314
|
+
end
|
|
315
|
+
end
|
|
316
|
+
end
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
- `sources(result)` gets what `call` returned and returns at most 25 hashes of `kind:`, `id:`, `title:` and `url:`. `title`
|
|
320
|
+
is what a person reads under the answer, at most 200 characters. `id` is how the record is named in the result,
|
|
321
|
+
a text or a whole number of at most 100 characters, so that NeetoAssist can tell which source is which record.
|
|
322
|
+
`url` is the record's own page in the product, `http` or `https`. `kind` is `"conversation"` for an exchange with
|
|
323
|
+
a customer and `"record"` for anything else that has a page of its own, such as an issue. `kind`, `id` and `url`
|
|
324
|
+
may be left out. Without a `kind`, NeetoAssist works it out for itself.
|
|
325
|
+
- **Build `url` from the record and the product's own routes. It must never be a text a customer wrote**, such as a
|
|
326
|
+
link from a message or a website from a contact's traits: a link under an answer is trusted for being the
|
|
327
|
+
product's own.
|
|
328
|
+
- A title is read by the rep, so translate it as the host translates its own screens. Cut a title built from a
|
|
329
|
+
customer's name to 200 characters, since a longer one is left out.
|
|
330
|
+
- The engine checks every source before it leaves the host. A title loses the characters that turn the direction
|
|
331
|
+
of text around (U+202A to U+202E, U+2066 to U+2069, U+200E, U+200F, U+061C) and its runs of white space first.
|
|
332
|
+
One that is not a hash, has no title (nothing but those characters is none), a title over 200 characters, a
|
|
333
|
+
`kind` other than `"conversation"` or `"record"` (a symbol of either is read as the text), an id that is neither
|
|
334
|
+
a text nor a whole number or is over 100 characters, or a `url` that is not an `http` or `https` address of at
|
|
335
|
+
most 2,000 characters without a username or a password is left out, and so is every one after the 25th. Only the first 100 a tool names are looked at, and the rest count as left out. Each call
|
|
336
|
+
that leaves one out is reported to Honeybadger once, with how many and why, never with a title or an address.
|
|
337
|
+
`sources` that raise, or that are not a list, mean none, and are reported too. The lookup's result goes either
|
|
338
|
+
way: a mistake here costs a person the link, never the answer.
|
|
339
|
+
- `sources` runs where `call` runs, as the rep, with writes to the database refused.
|
|
340
|
+
- An `id` goes to NeetoAssist as a text: `412` is `"412"`.
|
|
341
|
+
- A [product lookup](#the-assistant-and-product-lookups) names no sources: it is listed by itself.
|
|
255
342
|
|
|
256
343
|
#### An action
|
|
257
344
|
|
|
@@ -405,7 +492,8 @@ end
|
|
|
405
492
|
|
|
406
493
|
- With every question it sends NeetoAssist the definitions of the tools and actions that are `available?` for the
|
|
407
494
|
rep, along with the rep's role and the `context`.
|
|
408
|
-
- NeetoAssist takes at most
|
|
495
|
+
- NeetoAssist takes at most 64 tools (the host's own and the [product lookups](#the-assistant-and-product-lookups)
|
|
496
|
+
together) and 24 actions, with names that are unique across all of them. A class that breaks
|
|
409
497
|
one of NeetoAssist's limits, that cannot be described or that raises is left out and reported to Honeybadger, and
|
|
410
498
|
the rep still gets an answer. What makes a tool or an action unusable:
|
|
411
499
|
- a name that is not like `list_teammates` (a lower case letter, then letters, digits and underscores, at most
|
|
@@ -413,7 +501,7 @@ end
|
|
|
413
501
|
- no description, or one over 1,000 characters;
|
|
414
502
|
- a label that is not a text of at most 120 characters;
|
|
415
503
|
- params over 4,000 bytes as JSON;
|
|
416
|
-
- being the
|
|
504
|
+
- being the 65th tool or the 25th action;
|
|
417
505
|
- for an action: a name over 56 characters, or a param called `reason`;
|
|
418
506
|
- for an action that `writes`: a kind whose name is not like `github_issue`, no field or more than five, or a
|
|
419
507
|
field that is not one of the action's own `:string` params;
|
|
@@ -443,6 +531,178 @@ no class, no adapter method and no setup.
|
|
|
443
531
|
no answer in time, the rep is told that NeetoAssist cannot be reached, and the card says what became of the
|
|
444
532
|
action once NeetoAssist knows.
|
|
445
533
|
|
|
534
|
+
### The assistant and product lookups
|
|
535
|
+
|
|
536
|
+
A product can offer NeetoAssist anywhere in it as each person's own assistant: a thread that belongs to the person
|
|
537
|
+
who asks, with no conversation and no customer. And NeetoAssist can use the product's own read tools there, and on a
|
|
538
|
+
conversation: its MCP tools, which the product's teams keep. These are **product lookups**.
|
|
539
|
+
|
|
540
|
+
```ruby
|
|
541
|
+
module NeetoAssist
|
|
542
|
+
class HostAdapter < NeetoAssistEngine::HostAdapter
|
|
543
|
+
def enabled?(organization)
|
|
544
|
+
organization.neeto_assist_enabled?
|
|
545
|
+
end
|
|
546
|
+
|
|
547
|
+
def assistant?(user)
|
|
548
|
+
user.active?
|
|
549
|
+
end
|
|
550
|
+
|
|
551
|
+
def product_lookups(_user, _conversation)
|
|
552
|
+
NeetoAssistEngine::ProductLookups.all
|
|
553
|
+
end
|
|
554
|
+
|
|
555
|
+
def assistant_context(user, page)
|
|
556
|
+
booking = find_booking_from_path(user, page["path"])
|
|
557
|
+
booking ? { booking: { id: booking.id, sid: booking.sid } } : {}
|
|
558
|
+
end
|
|
559
|
+
|
|
560
|
+
def assistant_suggestions(_user)
|
|
561
|
+
[I18n.t("neeto_assist.suggestions.bookings_last_week")]
|
|
562
|
+
end
|
|
563
|
+
end
|
|
564
|
+
end
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
- `ProductLookups.all` offers every tool of the product's MCP registry (`Rails.application.config.mcp_tools`, which
|
|
568
|
+
neeto-commons-backend builds at boot) whose annotations say `readOnlyHint: true`, except the workspace chooser
|
|
569
|
+
`ListWorkspaces`. A read tool whose annotations say `openWorldHint: true` is not offered either: that is how a
|
|
570
|
+
product marks a tool with effects outside the workspace, such as an export that mails a file. MCP reads a missing
|
|
571
|
+
hint as true, and a tool built on neeto-commons-backend always says one or the other.
|
|
572
|
+
`ProductLookups.all(except: %w[GetX])` leaves tools out by name. `ProductLookups.none` offers none. The registry
|
|
573
|
+
is read on every question, so a read tool the product ships reaches NeetoAssist with its next deploy and no
|
|
574
|
+
change here.
|
|
575
|
+
- A tool is offered as the product wrote it: its name, its description (cut to 1,000 characters), a label from its
|
|
576
|
+
`invocation_messages(invoking:)`, else its title, and its arguments without the `workspace` argument and
|
|
577
|
+
`$schema`. A tool whose name NeetoAssist would not take (`/\A[A-Za-z][A-Za-z0-9_]{1,62}\z/`), with no
|
|
578
|
+
description, or with arguments over 4,000 bytes is left out and reported. The host's own tools come first, and a
|
|
579
|
+
product lookup with the name of one of them is left out.
|
|
580
|
+
- With them goes the product's own guidance for a model, `NeetoCommonsBackend::Mcp.config.instructions`, cut to
|
|
581
|
+
8,000 characters, when at least one product lookup is offered.
|
|
582
|
+
- A product lookup is asked for and run through the `mcp` gem's own server, in-process, as the hosted MCP endpoint
|
|
583
|
+
runs it after sign-in: with the person, their workspace as the only granted one, and the `read` scope alone. No
|
|
584
|
+
HTTP and no token. A tool that needs more than the read scope says so and runs nothing.
|
|
585
|
+
- **It never runs without a person.** In a product's MCP tools a missing user means an admin, so the engine refuses
|
|
586
|
+
before anything is built when there is no user, the user is inactive or belongs to another workspace.
|
|
587
|
+
- Its result is the tool's structured content, or `{ "text": "..." }` for a tool that answers in words, and its
|
|
588
|
+
summary for the pane is "12 found" when the result has a `total_count`. Arguments the MCP layer refuses are
|
|
589
|
+
`422 invalid_arguments`, and a tool that runs and reports an error is `422 failed` with its text (500 characters
|
|
590
|
+
at most). Each run is logged with the tool's name, the person's id and the run id, never the arguments.
|
|
591
|
+
- Unlike a host's tool, a product lookup runs with writes to the database allowed, since some product tools store a
|
|
592
|
+
refreshed calendar token while they read. The read scope and the read-only list are the guard.
|
|
593
|
+
- A product lookup has a limit of the engine's own, `config.product_lookup_timeout`, 20 seconds by default. The
|
|
594
|
+
product's MCP layer gives a tool a minute, and NeetoAssist stops waiting long before that, so a lookup that runs
|
|
595
|
+
past the limit is stopped and is `422 failed`, with words that tell NeetoAssist to ask for less. Write protection
|
|
596
|
+
is back as it was either way.
|
|
597
|
+
- The registry is another team's code, so a mistake in it costs only the tool it is in. Each tool is listed through
|
|
598
|
+
a server of its own: one whose annotations or listing raise is left out and reported once, and of two tools with
|
|
599
|
+
one name the first is offered and the second reported. A registry that cannot be read at all is reported and
|
|
600
|
+
gives no product lookups; the host's own tools are offered all the same.
|
|
601
|
+
- The engine never requires the `mcp` gem. A host without it, or without a registry, simply has no product lookups.
|
|
602
|
+
|
|
603
|
+
The assistant's thread is named by a key (`/\A[a-z0-9]{8,40}\z/`). Its id at NeetoAssist is
|
|
604
|
+
`assistant-<the signed-in person's id>-<key>`, built from the session on every request and never from the browser,
|
|
605
|
+
so a person only ever reaches their own threads. A question in it carries the host's `assistant_tools` and the
|
|
606
|
+
product lookups (`product_lookups(user, nil)`), a grant for the thread,
|
|
607
|
+
`conversation: { kind: "assistant", owner_id:, messages: [] }`, and as its context `assistant_context(user, page)`
|
|
608
|
+
with the page under `"page"` unless the host put one there (the path cut to 500 characters, the title to 200).
|
|
609
|
+
Before the host's `assistant_context` or NeetoAssist sees the page, its path loses everything from the first `?`
|
|
610
|
+
or `#`: query strings and fragments can hold a client's name or email.
|
|
611
|
+
The assistant only looks things up: it offers no actions, the host's or NeetoAssist's own, so a question there says
|
|
612
|
+
`"actions": []` and offers no commands.
|
|
613
|
+
|
|
614
|
+
### Shared lookups for a person asking in another product
|
|
615
|
+
|
|
616
|
+
A rep who asks NeetoAssist on a conversation in one Neeto product can have it look things up in another Neeto
|
|
617
|
+
product of the same workspace, as the same person there. "Has this customer booked with us this week?" asked in
|
|
618
|
+
NeetoChat is answered with NeetoCal's own read tools, run in NeetoCal as the rep's NeetoCal self. These are
|
|
619
|
+
**shared lookups**. Two engines take part: the one in the product the person asks in (the host) and the one in the
|
|
620
|
+
product whose data is read (the data product).
|
|
621
|
+
|
|
622
|
+
**In the host**, nothing needs to be written. The engine answers `POST /neeto_assist/api/v1/server/identity` for
|
|
623
|
+
NeetoAssist: for one of the host's own grants, checked as for any lookup, it says which workspace and which person
|
|
624
|
+
the grant stands for, by their NeetoAuth guids, and nothing else about them:
|
|
625
|
+
|
|
626
|
+
```json
|
|
627
|
+
{ "workspace": { "guid": "…", "subdomain": "acme" }, "person": { "guid": "…" }, "locale": "en" }
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
Both guids are in lower case, and `locale` is the grant's. A workspace or a person without a `guid` (blank, or a
|
|
631
|
+
user model with no such method) is `422 { "error": "no_identity" }`, and that person gets no shared lookups. So who
|
|
632
|
+
is asking is always confirmed by the product that signed the grant, never taken from what the ask says.
|
|
633
|
+
|
|
634
|
+
**In the data product**, two things:
|
|
635
|
+
|
|
636
|
+
```ruby
|
|
637
|
+
# config/initializers/neeto_assist.rb
|
|
638
|
+
config.pass_public_key = ENV["NEETO_ASSIST_PASS_PUBLIC_KEY"]
|
|
639
|
+
|
|
640
|
+
# The host adapter: what a person who asks elsewhere gets here. Give them what they would get in this
|
|
641
|
+
# product's own assistant, and nothing more.
|
|
642
|
+
def shared_lookups(user)
|
|
643
|
+
user.neeto_assist_user? ? NeetoAssistEngine::ProductLookups.all : NeetoAssistEngine::ProductLookups.none
|
|
644
|
+
end
|
|
645
|
+
```
|
|
646
|
+
|
|
647
|
+
NeetoAssist then signs a pass for one person, one workspace, this product and one run, and calls two endpoints with
|
|
648
|
+
`Authorization: Bearer <product token>` and `X-Neeto-Assist-Pass: <pass>`:
|
|
649
|
+
|
|
650
|
+
| Endpoint | Body | Answer |
|
|
651
|
+
| --- | --- | --- |
|
|
652
|
+
| `POST /neeto_assist/api/v1/server/shared/catalog` | `{ "run_id": "..." }` | `200 { "product": "cal", "tools": [ ... ], "guidance": "..." }`. `tools` are the shared lookups' definitions, as a question carries product lookups. `guidance` is `null` when none is shared. |
|
|
653
|
+
| `POST /neeto_assist/api/v1/server/shared/tool_calls` | `{ "tool": "ListBookings", "arguments": { ... }, "run_id": "..." }` | As `server/tool_calls` answers a product lookup. |
|
|
654
|
+
|
|
655
|
+
A call is allowed only when all of these hold, and anything else is `403 { "error": "forbidden" }`, the same answer
|
|
656
|
+
for every check, so a caller learns nothing about which one failed. A missing or wrong token is `401`.
|
|
657
|
+
|
|
658
|
+
1. The product token is this product's own, and the call names no `Origin`.
|
|
659
|
+
2. `pass_public_key` is set and is an Ed25519 public key, and the pass's signature verifies with it.
|
|
660
|
+
3. The pass says `"v": 1`, its `aud` is this product's `config.product`, and its `exp` is in the future and at most
|
|
661
|
+
15 minutes away.
|
|
662
|
+
4. The workspace with the pass's `workspace_guid` exists, carries that guid, is the one the call is addressed to by
|
|
663
|
+
its subdomain, is not disabled in the product, and the adapter's `enabled?` is true for it.
|
|
664
|
+
5. `find_user_by_guid` finds a person who carries the pass's `person_guid`, belongs to that workspace and is active.
|
|
665
|
+
Nothing is built before that: in the product's MCP tools a missing person means an admin.
|
|
666
|
+
6. For a tool call, `shared_lookups(user)` offers the tool. A tool that is not shared, a write, the product's own
|
|
667
|
+
`tools`, actions, a name the product does not have: all `403`, never `404`.
|
|
668
|
+
|
|
669
|
+
The catalog holds the product lookups `shared_lookups` gives, by every rule of product lookups above (read-only, no
|
|
670
|
+
`openWorldHint`, the person's own access, the read scope alone, `product_lookup_timeout`), and never the host's
|
|
671
|
+
own tools or actions. A lookup runs as that person, in the pass's language (one the product does not have means
|
|
672
|
+
its default one), with writes allowed as for any product lookup. Each run is logged with the tool's name, the
|
|
673
|
+
person's id, the product they asked in and the run, never the arguments.
|
|
674
|
+
|
|
675
|
+
The pass is two parts joined by a full stop, each base64url without padding (padded parts are read too): a JSON
|
|
676
|
+
object `{ "v": 1, "aud", "host", "workspace_guid", "person_guid", "run_id", "locale", "exp" }`, and the Ed25519
|
|
677
|
+
signature over the first part as it was sent. Verifying it never raises, whatever arrives. Guids are compared in
|
|
678
|
+
lower case.
|
|
679
|
+
|
|
680
|
+
Without `pass_public_key`, or with one that cannot be read, is not Ed25519 or holds a private key, the two shared
|
|
681
|
+
endpoints answer `403` and everything else works as before. A key that cannot be used is reported to Honeybadger
|
|
682
|
+
once, without its text, when it is first needed. The key may come straight from an environment variable: the two
|
|
683
|
+
characters `\n` are read as line breaks and white space around it does not count.
|
|
684
|
+
|
|
685
|
+
A test in the data product makes its own key pair and signs a pass as NeetoAssist does:
|
|
686
|
+
|
|
687
|
+
```ruby
|
|
688
|
+
key = OpenSSL::PKey.generate_key("ED25519")
|
|
689
|
+
NeetoAssistEngine.configuration.pass_public_key = key.public_to_pem # put the old value back after the test
|
|
690
|
+
|
|
691
|
+
payload = {
|
|
692
|
+
v: 1, aud: "cal", workspace_guid: organization.guid, person_guid: user.guid, host: "chat",
|
|
693
|
+
run_id: "run-1", locale: "en", exp: 10.minutes.from_now.to_i
|
|
694
|
+
}
|
|
695
|
+
signed = Base64.urlsafe_encode64(payload.to_json, padding: false)
|
|
696
|
+
pass = "#{signed}.#{Base64.urlsafe_encode64(key.sign(nil, signed), padding: false)}"
|
|
697
|
+
|
|
698
|
+
post "/neeto_assist/api/v1/server/shared/tool_calls",
|
|
699
|
+
params: { tool: "ListBookings", arguments: {}, run_id: "run-1" }.to_json,
|
|
700
|
+
headers: {
|
|
701
|
+
"Content-Type" => "application/json", "Authorization" => "Bearer #{NeetoAssistEngine.configuration.api_token}",
|
|
702
|
+
"X-Neeto-Assist-Pass" => pass
|
|
703
|
+
}
|
|
704
|
+
```
|
|
705
|
+
|
|
446
706
|
### The grant, and what a host trusts
|
|
447
707
|
|
|
448
708
|
NeetoAssist's servers are not signed in to the host. What lets them look something up is a grant.
|
|
@@ -457,12 +717,17 @@ On every call from NeetoAssist's servers the engine checks, in this order:
|
|
|
457
717
|
|
|
458
718
|
1. The product token is the host's own `config.api_token`, compared in constant time. Otherwise the answer is `401`.
|
|
459
719
|
2. The grant verifies: signed by this host, for lookups, not expired.
|
|
460
|
-
3. Its workspace exists, and the call is addressed to that workspace's subdomain.
|
|
461
|
-
4. `enabled?` is true for the workspace.
|
|
720
|
+
3. Its workspace exists, is not disabled in the product, and the call is addressed to that workspace's subdomain.
|
|
721
|
+
4. The adapter's `enabled?` is true for the workspace.
|
|
462
722
|
5. `find_user` finds the rep, and the rep has not been deactivated.
|
|
463
723
|
6. `find_conversation` finds the conversation, by the id it found it by when the rep asked.
|
|
464
724
|
7. `can_use?` is true for that rep on that conversation.
|
|
465
725
|
|
|
726
|
+
A grant for one of a person's assistant threads names `assistant-<the grant's person's id>-<key>` instead of a
|
|
727
|
+
conversation. For it, steps 6 and 7 are: the key is a key, and `assistant?` is true for the person. Its lookups are
|
|
728
|
+
the host's `assistant_tools` and the product lookups. It has no actions, so an action preview asked for with it is
|
|
729
|
+
`404 unknown_action`.
|
|
730
|
+
|
|
466
731
|
Anything else is `403`. Nothing is taken from a session or a cookie. A rep who loses the conversation, or the
|
|
467
732
|
workspace, loses the lookups at once, not when the grant expires.
|
|
468
733
|
|
|
@@ -482,10 +747,16 @@ What a host is trusting when it installs the engine:
|
|
|
482
747
|
- **A grant is signed with the host's `secret_key_base`.** Rotating that ends every grant.
|
|
483
748
|
- **A workspace's IP restriction does not stop NeetoAssist.** Its servers are on no workspace's list of allowed
|
|
484
749
|
addresses, so when the host boots the engine adds a Rack::Attack safelist, named "NeetoAssist lookups", for a
|
|
485
|
-
`POST` to one of the
|
|
486
|
-
without Rack::Attack
|
|
487
|
-
|
|
488
|
-
|
|
750
|
+
`POST` to one of the server endpoints (`tool_calls`, `action_previews`, `identity`, `shared/catalog` and
|
|
751
|
+
`shared/tool_calls`) that carries the product token. Nothing else is safelisted, and a host without Rack::Attack
|
|
752
|
+
gets none.
|
|
753
|
+
- **The grant and the pass stay out of error reports.** When the host boots the engine adds `neeto_assist_grant`
|
|
754
|
+
and `neeto_assist_pass` to the host's `filter_parameters`, which Honeybadger also applies to a request's headers.
|
|
755
|
+
- **A lookup's arguments stay out of the host's request log.** They can hold what a customer wrote. On the
|
|
756
|
+
engine's server endpoints alone, each request filters the parameter `arguments` (that exact key) out of what
|
|
757
|
+
Rails logs and of anything else built from the request's filtered parameters, such as lograge or an error
|
|
758
|
+
report. The tool or the preview still gets them whole. The host's own `filter_parameters` is not changed, so a
|
|
759
|
+
parameter of that name on the host's other endpoints is logged as the host decides.
|
|
489
760
|
|
|
490
761
|
The safelist and the filter entry are the only two things the engine changes in the host by itself. Neither needs
|
|
491
762
|
any setup, and neither can be switched off.
|
|
@@ -514,16 +785,32 @@ The pane calls these for the signed-in rep, under the mount path:
|
|
|
514
785
|
|
|
515
786
|
| Endpoint | Does |
|
|
516
787
|
| --- | --- |
|
|
517
|
-
| `GET /neeto_assist/api/v1/status` | `200 { "enabled": true
|
|
788
|
+
| `GET /neeto_assist/api/v1/status` | `200 { "enabled": true, "assistant": true }`, for any signed-in rep. `assistant` says whether NeetoAssist is on and `assistant?` is true for this person. |
|
|
518
789
|
| `GET /neeto_assist/api/v1/conversations/:conversation_id/runs` | NeetoAssist's runs for the conversation as the signed-in rep may see them, newest first: every reply suggestion, and the rep's own questions, each with the lookups it made (`steps`) and the actions it suggested (`actions`). Another rep's questions are not among them. With them come the workspace's credits and the commands the rep can pick in the box: `{ "runs": [...], "credits": { "exhausted", "remaining", "buy_url" }, "commands": [{ "name", "title", "description" }] }`. `buy_url` is `null` unless `can_buy_credits?` is true for the rep. |
|
|
519
790
|
| `POST /neeto_assist/api/v1/conversations/:conversation_id/runs` | Asks NeetoAssist the rep's question: `{ "run": { "question": "..." } }`. The engine adds the rep's role, the tools and actions the rep may use, a grant and the `context`. |
|
|
520
791
|
| `PUT /neeto_assist/api/v1/conversations/:conversation_id/runs/:run_id/feedback` | Rates a run: `{ "feedback": { "rating": "up", "note": "..." } }`. |
|
|
792
|
+
| `POST /neeto_assist/api/v1/conversations/:conversation_id/runs/:id/stop` | Stops the rep's own question while NeetoAssist is still on it. No body. Answers `{ "run": { ... } }`, the run as it now stands: `stopped`, or as it ended when its answer came first. |
|
|
521
793
|
| `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/apply` | Runs a suggested action as the signed-in rep, or has NeetoAssist run one of its own for that rep. |
|
|
522
794
|
| `POST /neeto_assist/api/v1/conversations/:conversation_id/actions/:id/dismiss` | Dismisses a suggested action. |
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
795
|
+
| `GET /neeto_assist/api/v1/assistant/thread` | `{ "thread": { "id": "<key>" }, "suggestions": [...] }`: the person's latest assistant thread, or a fresh key when they have none or NeetoAssist cannot be reached, with `assistant_suggestions`. |
|
|
796
|
+
| `POST /neeto_assist/api/v1/assistant/thread` | `201 { "thread": { "id": "<new key>" } }`, a new chat. Nothing is stored until its first question. |
|
|
797
|
+
| `GET /neeto_assist/api/v1/assistant/threads/:thread_id/runs` | The thread's runs, as on a conversation. |
|
|
798
|
+
| `POST /neeto_assist/api/v1/assistant/threads/:thread_id/runs` | Asks in the thread: `{ "run": { "question": "...", "request_id": "..." }, "page": { "path": "...", "title": "..." } }`. |
|
|
799
|
+
| `PUT /neeto_assist/api/v1/assistant/threads/:thread_id/runs/:run_id/feedback` | Rates a run, as on a conversation. |
|
|
800
|
+
| `POST /neeto_assist/api/v1/assistant/threads/:thread_id/runs/:id/stop` | Stops the person's own question in the thread, as on a conversation. |
|
|
801
|
+
|
|
802
|
+
- The conversation endpoints answer 404 unless `enabled?`, `find_conversation` and `can_use?` all pass. The
|
|
803
|
+
assistant endpoints answer 404 unless `enabled?` and `assistant?` pass, and for a thread key that is no key.
|
|
804
|
+
- Who asks, rates, applies, dismisses or stops is always the signed-in rep (id, name, email), never anything in the
|
|
526
805
|
request.
|
|
806
|
+
- Every list of runs that NeetoAssist answered, on a conversation and in a thread, carries `"can_stop": true`, added
|
|
807
|
+
by the engine whatever NeetoAssist sent, so that a pane shows its stop button only with an engine that has these
|
|
808
|
+
two endpoints. A list that failed does not carry it.
|
|
809
|
+
- A stop says who wants the question stopped (`stopped_by`, the rep's id), and NeetoAssist stops only a question
|
|
810
|
+
that rep asked and that is still queued or running. The engine does not know who asked, and does not guess. A run
|
|
811
|
+
that is not the rep's own ask on this conversation is `404`. Any other answer of NeetoAssist's that is no success
|
|
812
|
+
is `503 unavailable`. A stopped run has the status `stopped`, keeps its
|
|
813
|
+
question and the steps made so far, and has no answer.
|
|
527
814
|
- An answer to a question is built from lookups made with the asker's access, so only the rep who asked is shown
|
|
528
815
|
it. The engine tells NeetoAssist who is looking with every list (`requested_by_id`, the signed-in rep's id as
|
|
529
816
|
it was sent when they asked), and NeetoAssist leaves out the questions of everyone else.
|
|
@@ -573,9 +860,17 @@ NeetoAssist's own servers call the next two, with `Authorization: Bearer <produc
|
|
|
573
860
|
|
|
574
861
|
| Endpoint | Body | Answer |
|
|
575
862
|
| --- | --- | --- |
|
|
576
|
-
| `POST /neeto_assist/api/v1/server/tool_calls` | `{ "tool": "list_teammates", "arguments": { ... }, "run_id": "..." }` | `200 { "result": ..., "summary": "3 people" }`. `summary` is `null` when the tool has none. |
|
|
863
|
+
| `POST /neeto_assist/api/v1/server/tool_calls` | `{ "tool": "list_teammates", "arguments": { ... }, "run_id": "..." }` | `200 { "result": ..., "summary": "3 people", "sources": [{ "kind": "conversation", "id": "412", "title": "...", "url": "https://..." }] }`. `summary` is `null` when the tool has none, and `sources` is `[]` ([its rules](#a-tool-that-names-its-sources)). A source has no `kind`, `id` or `url` key when the tool gave none. For a product lookup `result` is the tool's structured content, or `{ "text": "..." }`, and `sources` is `[]`. |
|
|
577
864
|
| `POST /neeto_assist/api/v1/server/action_previews` | `{ "name": "assign_conversation", "arguments": { ... }, "run_id": "..." }` | `200 { "preview": { "title": "Assign to Priya Sharma", "details": ["Team: Billing"] } }`. The preview has a `content` too when the action's `Preview` has one. |
|
|
578
865
|
|
|
866
|
+
NeetoAssist also asks `POST /neeto_assist/api/v1/server/identity` with the same two headers and `{ "run_id": "..." }`
|
|
867
|
+
([above](#shared-lookups-for-a-person-asking-in-another-product)), and, in a product that shares its lookups,
|
|
868
|
+
the two `shared/` endpoints with a pass in place of the grant.
|
|
869
|
+
|
|
870
|
+
Every server endpoint refuses a disabled workspace with `403 { "error": "forbidden" }`, on both the grant and
|
|
871
|
+
pass paths, even when its NeetoAssist flag is still on. Hosts whose workspace model has no `enabled` state are
|
|
872
|
+
unaffected.
|
|
873
|
+
|
|
579
874
|
Both only read, and neither looks at a session or a cookie. Their errors are
|
|
580
875
|
`{ "error": "<code>", "message": "<a sentence, for some>" }`:
|
|
581
876
|
|
|
@@ -658,7 +953,7 @@ const TicketHeader = ({
|
|
|
658
953
|
such as "Sam Smith's conversation". The pane shows "Looking at Sam Smith's conversation" under its header, as plain
|
|
659
954
|
text, so the rep knows what NeetoAssist's answers are about. Leave it out to show no such line.
|
|
660
955
|
- The pane shows what NeetoAssist did on the ticket, oldest first: what the customer wrote with the suggested
|
|
661
|
-
reply, "Use reply", "Copy" and the
|
|
956
|
+
reply, "Use reply", "Copy" and the sources it came from; the rep's own questions as a chat, each with what
|
|
662
957
|
NeetoAssist looked up to answer it, its answer and a card for every action it suggests; the reason it skipped or
|
|
663
958
|
found no answer; thumbs up or down with an optional note; then a box to ask more. Another rep's questions and
|
|
664
959
|
their answers are not shown. A ticket with none of these starts with a short introduction and a few suggested
|
|
@@ -675,6 +970,27 @@ const TicketHeader = ({
|
|
|
675
970
|
without commands gets no menu and no such line, and the box is the plain one it always was.
|
|
676
971
|
- A question that NeetoAssist read as a command shows as it was typed, with the command a little heavier than the
|
|
677
972
|
words after it.
|
|
973
|
+
- When the list of runs says `can_stop` (this engine always does), and while the rep's own latest question is
|
|
974
|
+
queued or running, the send button is a stop button, as in Neeti. One
|
|
975
|
+
click stops the question (the `stop` [endpoints](#endpoints)); the button shows it is working until the list says the
|
|
976
|
+
question has ended, and a second click meanwhile sends nothing. A stop that failed shows the pane's usual error
|
|
977
|
+
under the box and leaves the button to try again. The box stays open, and the keyboard stays in it, but Enter
|
|
978
|
+
sends nothing until the question has ended. A reply suggestion that is being written has no stop button and
|
|
979
|
+
holds nothing up. A stopped question shows what was asked, what was looked up folded into one line, and the
|
|
980
|
+
muted line "Stopped before NeetoAssist answered.", which a screen reader reads out. It has no thumbs. A list
|
|
981
|
+
without `can_stop`, from an older engine, leaves the box as it always was: the send button stays, a second
|
|
982
|
+
question can be sent while the first runs, and there is no stop button.
|
|
983
|
+
- Under an answer, "Sources" lists what it rests on, one to a line: what kind of thing it is in a muted word ("Help
|
|
984
|
+
article", "API docs", nothing for a conversation, whose title says it is one, or another record, the product's
|
|
985
|
+
name for a lookup), then its title. A title with an `http` or `https` address opens it in a new tab; any other
|
|
986
|
+
address, and one with a name or password before an `@`, is never a link, and a
|
|
987
|
+
source without one, such as a lookup, is plain text. A source with no `kind`, as an older NeetoAssist sends,
|
|
988
|
+
is a help article, and one with neither a title nor a web address is left out. Everything in the list is shown as
|
|
989
|
+
text.
|
|
990
|
+
- Beside the thumbs of the rep's own answered question, "Copy answer" copies the answer as plain text: the words
|
|
991
|
+
without the light markdown around them, a list with its numbers or dashes, a table as the lines it was written
|
|
992
|
+
in, and a block of code as its lines. The button turns into a check for a moment, only when the copy went
|
|
993
|
+
through; where the browser refuses, the shared copy helper tries its own way and says in a toast how it went.
|
|
678
994
|
- What NeetoAssist looked up shows as a quiet list while it works: each lookup's label with a spinner, a check or a
|
|
679
995
|
cross, and a few words on what it found. Once the answer is there the list folds into one line, such as "Looked at 3
|
|
680
996
|
things", that opens to the same list.
|
|
@@ -709,10 +1025,103 @@ const TicketHeader = ({
|
|
|
709
1025
|
`**bold**`, `1.` numbered and `-` bulleted lists, `##` headings). `html` is the same reply for a rich-text
|
|
710
1026
|
composer: escaped text inside only `p`, `br`, `strong`, `ol`, `ul`, `li` and `h2`, with no attributes, so no
|
|
711
1027
|
markup from the conversation survives as HTML. A name the model set off in backticks, such as a file name,
|
|
712
|
-
arrives in `html` as plain words.
|
|
1028
|
+
arrives in `html` as plain words. A fenced block of code arrives as its lines: in `text` with only the lines of
|
|
1029
|
+
three backticks around it left out, in `html` as a paragraph of its escaped lines. Leave `onUseReply` out to show
|
|
1030
|
+
only "Copy".
|
|
1031
|
+
- A workspace whose team reads English can have NeetoAssist send a reply in English and in the language the
|
|
1032
|
+
customer is sent it in. That is switched on in NeetoAssist, per workspace, and the engine hands a run to the pane
|
|
1033
|
+
as it came, so a host does nothing for it. Such a run carries up to five more fields. `suggestedReplyInEnglish`
|
|
1034
|
+
and `suggestedReplyInCustomerLanguage` are the reply both ways, and `suggestedReplyLanguage` is the BCP 47 tag of
|
|
1035
|
+
the language the second one is in, such as `es` or `pt-BR`, never English. The three are there together or not at
|
|
1036
|
+
all. The reply as written is what the customer is sent, unless it is English: a reply written in another language
|
|
1037
|
+
is `suggestedReplyInCustomerLanguage`, word for word, and `suggestedReplyInEnglish` is its translation, while a
|
|
1038
|
+
reply written in English is `suggestedReplyInEnglish`, and `suggestedReplyInCustomerLanguage` is its translation
|
|
1039
|
+
into the customer's language. No reply is translated twice. `customerLanguage` is the tag of the language the
|
|
1040
|
+
customer writes in, when NeetoAssist could tell and it is not English. It can be missing beside a reply's
|
|
1041
|
+
readings, when the customer wrote too little to tell by, and it can be another language than the reply's, when a
|
|
1042
|
+
rep asked for the reply in one of their choosing. `questionInEnglish` is what the customer wrote, in English, on
|
|
1043
|
+
a reply suggestion only. `suggestedReply` and `question` stay what they always were. A run without the fields
|
|
1044
|
+
looks and works as it always did.
|
|
1045
|
+
- The card of a reply that has `suggestedReplyLanguage` and both readings shows the English one. Under it, a muted
|
|
1046
|
+
line says "The customer writes in Spanish." when `customerLanguage` names the same language as the reply's (the
|
|
1047
|
+
first parts of the two tags match, so `pt-PT` beside `pt-BR` does), and "This reply is in French." when it names
|
|
1048
|
+
another or is missing. The link beside it, "Show in Spanish", turns the card to the reading the customer is sent
|
|
1049
|
+
and then reads "Show in English". The buttons are "Use in Spanish", which is the main one and keeps the test id
|
|
1050
|
+
of "Use reply" (`neeto-assist-use-reply-button`), "Use in English" and "Copy". The link and the buttons name the
|
|
1051
|
+
reply's language. `onUseReply(text, html)` gets the reading the rep picked, made into `text` and `html` as above,
|
|
1052
|
+
whichever reading is showing, and "Copy" copies the one that is showing. Without `onUseReply` there is "Copy"
|
|
1053
|
+
alone, and the link still turns the card. With one reading alone, or without `suggestedReplyLanguage`, the card
|
|
1054
|
+
is the one it always was.
|
|
1055
|
+
- "Customer wrote" shows the customer's words in English when a reply suggestion has `questionInEnglish`, with
|
|
1056
|
+
"Translated from Spanish." under them and the link "Show original". The link turns them to the customer's own
|
|
1057
|
+
words, and the line then says "Original in Spanish." and the link "Show in English". The language is
|
|
1058
|
+
`customerLanguage` alone, whatever the reply is in, and without it the lines are "Translated." and "Original.".
|
|
1059
|
+
Both readings are plain text. A rep's own question is never translated.
|
|
1060
|
+
- A language's name comes from the browser (`Intl.DisplayNames`), in the language the pane is in, and English is
|
|
1061
|
+
named the same way. Where the browser has no name for a tag, or throws at it, the sentences have a form without
|
|
1062
|
+
a name ("The customer writes in another language.", "This reply is in another language.", "Use in their
|
|
1063
|
+
language", "Show in their language", "Translated.", "Original."), and a tag is never shown to the rep.
|
|
1064
|
+
- The block that shows a reading has `lang` (the tag, or `en`), so a screen reader picks the right voice, and reads
|
|
1065
|
+
the other reading out when the rep turns it. Its direction comes from the language and its letters, not from
|
|
1066
|
+
the reading's first letter: `dir="rtl"` when the language is Arabic, Hebrew, Persian, Urdu, Pashto, Sindhi,
|
|
1067
|
+
Uyghur, Yiddish, Dhivehi or Sorani (`ar`, `he`, `fa`, `ur`, `ps`, `sd`, `ug`, `yi`, `dv` and `ckb`, by the first
|
|
1068
|
+
part of the tag) and the reading holds a letter of a right-to-left script, `dir="ltr"` for the English reading,
|
|
1069
|
+
and `dir="auto"` for any other. So an Arabic reply that opens with the name of a product still reads right to
|
|
1070
|
+
left, and Urdu written in Latin letters is left to the text. The link is a button that keeps the keyboard
|
|
1071
|
+
through a turn. Each card and each "Customer wrote" remembers its turn only while it is on screen: nothing is
|
|
1072
|
+
stored.
|
|
713
1073
|
- The pane shows replies and notes with the same formatting, built as React elements around plain text. It
|
|
714
1074
|
shows a name in backticks as code, and a numbered list that carries on after bullets counts on from where it
|
|
715
|
-
stopped.
|
|
1075
|
+
stopped. A fenced block (three backticks on a line, with or without a language word after them, and three
|
|
1076
|
+
backticks to close it) shows as a block of code in a monospace font, its lines exactly as written and nothing in
|
|
1077
|
+
them read as markdown or coloured. A long line scrolls sideways inside the block, and a block that scrolls takes
|
|
1078
|
+
the keyboard. A fence that nothing closes shows as the text it was.
|
|
1079
|
+
- A markdown pipe table in an answer shows as a table, in a conversation and in the assistant alike. A wide table
|
|
1080
|
+
scrolls sideways in its own box, so the pane never does, and the box takes the keyboard so the arrow keys scroll
|
|
1081
|
+
it too. A table needs its header row and the line of dashes under it with as many cells; the pipes at the ends are
|
|
1082
|
+
optional, a short row gets empty cells, cells past the header's count are dropped, and a pipe inside backticks or
|
|
1083
|
+
escaped as `\|` stays in its cell. Anything short of that, or a table of more than 12 columns or 200 rows, shows
|
|
1084
|
+
as the text it was. Cells are formatted like any other text. What `onUseReply`'s `html` gets is unchanged by
|
|
1085
|
+
tables: the same as before the pane drew them, so a composer without tables loses nothing.
|
|
1086
|
+
|
|
1087
|
+
### The assistant
|
|
1088
|
+
|
|
1089
|
+
A product can also give its people NeetoAssist as their own assistant, anywhere in the product: no conversation and
|
|
1090
|
+
no customer, a thread that belongs to the person who asks, and the product's own read tools as lookups (see the
|
|
1091
|
+
host adapter's `assistant?`, `product_lookups` and `assistant_suggestions`). It opens in the same `NeetoAssistPane`,
|
|
1092
|
+
so a product that already mounts the pane adds only its own way in:
|
|
1093
|
+
|
|
1094
|
+
```jsx
|
|
1095
|
+
import { useNeetoAssistAssistant } from "@bigbinary/neeto-assist-frontend";
|
|
1096
|
+
|
|
1097
|
+
const AssistantMenuItem = () => {
|
|
1098
|
+
const { isAvailable, isOpen, toggle } = useNeetoAssistAssistant();
|
|
1099
|
+
|
|
1100
|
+
if (!isAvailable) return null;
|
|
1101
|
+
|
|
1102
|
+
return <MenuItem active={isOpen} label="NeetoAssist" onClick={toggle} />;
|
|
1103
|
+
};
|
|
1104
|
+
```
|
|
1105
|
+
|
|
1106
|
+
- `useNeetoAssistAssistant()` returns `{ isAvailable, isOpen, open, close, toggle }`. `isAvailable` is the status
|
|
1107
|
+
endpoint's `assistant`: NeetoAssist is on and the host adapter's `assistant?` holds for this person. It is false
|
|
1108
|
+
while the status loads and after it failed. `isOpen` is true while the pane shows the assistant.
|
|
1109
|
+
- The pane shows whichever was opened last. Opening the assistant takes the pane from a ticket's conversation, and a
|
|
1110
|
+
click on that ticket's `NeetoAssistButton` brings the conversation back. `close` only closes the assistant. A
|
|
1111
|
+
product that never calls the hook gets exactly the conversation pane, and no request about the assistant is made.
|
|
1112
|
+
- The first time the assistant opens on a page, it asks the engine for the person's latest thread and the first
|
|
1113
|
+
questions the host offers. The header has New chat, expand and close. New chat starts an empty thread, and is off
|
|
1114
|
+
while NeetoAssist is still working on a question: stopping the question is the way to it sooner. An empty thread shows a few words on what the assistant is for
|
|
1115
|
+
and the host's questions as buttons that ask on a click; with none there is no list. After New chat and after a
|
|
1116
|
+
question is picked, the keyboard goes to the box.
|
|
1117
|
+
- The thread then reads like a conversation: each question, what NeetoAssist looked up while it worked, its answer
|
|
1118
|
+
with sources, and thumbs. There is no suggested reply, a card only when a run has one, and a command menu only when
|
|
1119
|
+
the engine lists commands. When credits are used up, the box and Stop stay while the person's ask is pending;
|
|
1120
|
+
the credits banner takes the box's place after it ends, as on a conversation. A failed request shows the pane's
|
|
1121
|
+
usual error in the pane, never a blank pane and never a toast.
|
|
1122
|
+
- Every question carries the page it was asked on: `location.pathname` and `document.title`, without a query
|
|
1123
|
+
string or fragment. The engine strips both again before the host adapter's `assistant_context` reads the page
|
|
1124
|
+
to say what the person is looking at, and before it goes to NeetoAssist.
|
|
716
1125
|
|
|
717
1126
|
## Development
|
|
718
1127
|
|