@oryksa/sdk 0.1.4 → 0.1.5
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.es.md +133 -91
- package/README.fr.md +133 -91
- package/README.md +133 -91
- package/README.pt.md +133 -91
- package/package.json +19 -19
- package/src/index.d.ts +91 -2
- package/src/index.js +719 -328
package/README.md
CHANGED
|
@@ -1,91 +1,133 @@
|
|
|
1
|
-
<p align="center"><img src="https://app.oryksa.com/static/oryksa_logo.png" width="300" alt="ORYKSA"></p>
|
|
2
|
-
|
|
3
|
-
# @oryksa/sdk
|
|
4
|
-
|
|
5
|
-
[](README.md) [](README.pt.md) [](README.es.md) [](README.fr.md)
|
|
6
|
-
|
|
7
|
-
<p align="center"><a href="https://developer.oryksa.com/en/sdks"><img src="https://developer.oryksa.com/assets/img/sdk/oryksa-sdks-en.gif" width="760" alt="ORYKSA SDKs: the AI chat and voice on iOS, Android, Flutter, React Native and the web"></a></p>
|
|
8
|
-
|
|
9
|
-
Official JavaScript and TypeScript SDK for **ORYKSA AI Employees**: put an AI employee that already knows the business inside your web app, Node backend or Electron desktop app. Same brain as WhatsApp and the website chat, text and voice.
|
|
10
|
-
|
|
11
|
-
- Docs: https://developer.oryksa.com
|
|
12
|
-
- API: `https://api.oryksa.com/v1`
|
|
13
|
-
|
|
14
|
-
## Screenshots
|
|
15
|
-
|
|
16
|
-
<p align="center"><img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_chat_en.png" width="420" alt="Chat"> <img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_theme_en.png" width="420" alt="Chat with the README theme"></p>
|
|
17
|
-
|
|
18
|
-
A store page with `mountChat`, captured by CI in Chrome with an ORYKSA test account (`test/shots.html`): default colors on the left, the code of *Colours and theme* below on the right.
|
|
19
|
-
|
|
20
|
-
## Install
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm install @oryksa/sdk
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Server (secret key)
|
|
27
|
-
|
|
28
|
-
```js
|
|
29
|
-
import { Oryksa } from "@oryksa/sdk";
|
|
30
|
-
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY); // developer.oryksa.com > Keys
|
|
31
|
-
|
|
32
|
-
const r = await oryksa.chat({ message: "Are you open on Saturday?" });
|
|
33
|
-
console.log(r.reply, r.conversation_id);
|
|
34
|
-
|
|
35
|
-
// Teach the AI employee about your app (e.g. on every release)
|
|
36
|
-
await oryksa.learnApp({
|
|
37
|
-
name: "FitTrack",
|
|
38
|
-
description: "Fitness app to log workouts and follow training plans.",
|
|
39
|
-
screens: [{ title: "Workouts", content: "Tap + to log a workout." }],
|
|
40
|
-
faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## In the app (session token, never the secret key)
|
|
45
|
-
|
|
46
|
-
```js
|
|
47
|
-
// your server
|
|
48
|
-
app.get("/oryksa-token", requireLogin, async (req, res) => {
|
|
49
|
-
const s = await oryksa.createSession({ conversationId: "user-" + req.user.id, customerName: req.user.firstName });
|
|
50
|
-
res.json({ token: s.client_token });
|
|
51
|
-
});
|
|
52
|
-
|
|
53
|
-
// your web app
|
|
54
|
-
import { OryksaClient, mountChat } from "@oryksa/sdk";
|
|
55
|
-
const client = new OryksaClient({ getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token });
|
|
56
|
-
mountChat({ client, lang: "en" }); // ready-made chat UI
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
##
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
```js
|
|
64
|
-
mountChat({
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
1
|
+
<p align="center"><img src="https://app.oryksa.com/static/oryksa_logo.png" width="300" alt="ORYKSA"></p>
|
|
2
|
+
|
|
3
|
+
# @oryksa/sdk
|
|
4
|
+
|
|
5
|
+
[](README.md) [](README.pt.md) [](README.es.md) [](README.fr.md)
|
|
6
|
+
|
|
7
|
+
<p align="center"><a href="https://developer.oryksa.com/en/sdks"><img src="https://developer.oryksa.com/assets/img/sdk/oryksa-sdks-en.gif" width="760" alt="ORYKSA SDKs: the AI chat and voice on iOS, Android, Flutter, React Native and the web"></a></p>
|
|
8
|
+
|
|
9
|
+
Official JavaScript and TypeScript SDK for **ORYKSA AI Employees**: put an AI employee that already knows the business inside your web app, Node backend or Electron desktop app. Same brain as WhatsApp and the website chat, text and voice.
|
|
10
|
+
|
|
11
|
+
- Docs: https://developer.oryksa.com
|
|
12
|
+
- API: `https://api.oryksa.com/v1`
|
|
13
|
+
|
|
14
|
+
## Screenshots
|
|
15
|
+
|
|
16
|
+
<p align="center"><img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_chat_en.png" width="420" alt="Chat"> <img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_theme_en.png" width="420" alt="Chat with the README theme"></p>
|
|
17
|
+
|
|
18
|
+
A store page with `mountChat`, captured by CI in Chrome with an ORYKSA test account (`test/shots.html`): default colors on the left, the code of *Colours and theme* below on the right.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @oryksa/sdk
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Server (secret key)
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
import { Oryksa } from "@oryksa/sdk";
|
|
30
|
+
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY); // developer.oryksa.com > Keys
|
|
31
|
+
|
|
32
|
+
const r = await oryksa.chat({ message: "Are you open on Saturday?" });
|
|
33
|
+
console.log(r.reply, r.conversation_id);
|
|
34
|
+
|
|
35
|
+
// Teach the AI employee about your app (e.g. on every release)
|
|
36
|
+
await oryksa.learnApp({
|
|
37
|
+
name: "FitTrack",
|
|
38
|
+
description: "Fitness app to log workouts and follow training plans.",
|
|
39
|
+
screens: [{ title: "Workouts", content: "Tap + to log a workout." }],
|
|
40
|
+
faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## In the app (session token, never the secret key)
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
// your server
|
|
48
|
+
app.get("/oryksa-token", requireLogin, async (req, res) => {
|
|
49
|
+
const s = await oryksa.createSession({ conversationId: "user-" + req.user.id, customerName: req.user.firstName });
|
|
50
|
+
res.json({ token: s.client_token });
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// your web app
|
|
54
|
+
import { OryksaClient, mountChat } from "@oryksa/sdk";
|
|
55
|
+
const client = new OryksaClient({ getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token });
|
|
56
|
+
mountChat({ client, lang: "en" }); // ready-made chat UI
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Links with an Open button (0.1.5)
|
|
60
|
+
|
|
61
|
+
The links the AI gives can be clicked in the chat (web addresses and e-mails), and each web link gets a card under her reply with the picture and title of the page and an **Open** button (the pages of your own site, the domains of your website chat; other sites show the address). Pass `onLink` to open your own pages, for example your product page: return true when your app opened it, false to open it in a new tab.
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
mountChat({
|
|
65
|
+
client, lang: "en",
|
|
66
|
+
onLink: (url) => {
|
|
67
|
+
const id = myProductIdOf(url); // your routes
|
|
68
|
+
if (!id) return false;
|
|
69
|
+
router.push("/product/" + id);
|
|
70
|
+
return true;
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`client.linkPreview(url)` gives the title and picture of a link (`null` when it cannot be read); `linksIn(text)` and `withoutLinks(text)` are exported too.
|
|
76
|
+
|
|
77
|
+
## Attach a photo or a document (0.1.5)
|
|
78
|
+
|
|
79
|
+
The chat of `mountChat` has an attach button: a photo from the library, the camera (phones and tablets) or a document (PDF, Word, text, CSV). Photos are made smaller before they go (up to 2 MB); documents up to 8 MB. The AI looks at the photo or reads the document. Turn it off with `attachments: false`. From code: `client.send(text, { image: { base64, mime } })` or `{ file: { base64, name, mime } }`.
|
|
80
|
+
|
|
81
|
+
## Your own AI features: `ai` (0.1.5)
|
|
82
|
+
|
|
83
|
+
Have the AI do what your app or site needs (read a photo, extract data, classify, translate, write) and pay with ORYKSA interactions: 1 per answer. Your prompt and your JSON Schema live in your code; the session token is enough (never ship the secret key). It does not create a conversation in your inbox.
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
const r = await client.ai({
|
|
87
|
+
instructions: "Read the tyre on the photo: brand, model and size exactly as written on the sidewall. " +
|
|
88
|
+
"If the size is not legible, readable=false and size=null. Never invent.",
|
|
89
|
+
images: [{ base64: photoBase64, mime: "image/jpeg" }], // resized to 1600 px
|
|
90
|
+
schema: {
|
|
91
|
+
type: "object",
|
|
92
|
+
properties: { readable: { type: "boolean" }, brand: { type: ["string", "null"] }, size: { type: ["string", "null"] } },
|
|
93
|
+
required: ["readable", "brand", "size"],
|
|
94
|
+
},
|
|
95
|
+
});
|
|
96
|
+
if (r.json?.readable) showProducts(r.json.size);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`r.text` has the answer as text, `r.json` the object (with a schema), `r.interactionsSpent` the interactions used. When the plan's interactions are used up the call rejects with `OryksaError` status 402.
|
|
100
|
+
|
|
101
|
+
## Colours and theme
|
|
102
|
+
|
|
103
|
+
`mountChat` accepts three colors as CSS strings: `accent` (buttons, visitor bubbles, links), `ink` (main text) and `soft` (AI bubbles). Missing ones keep the default (`#5B57E0`, `#161B3D` and `#EEEBFB`). `position` (`"left"` or `"right"`) picks the side of the screen.
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
mountChat({ client, lang: "en", accent: "#0E8A6B", ink: "#10281F", soft: "#E3F5EE" });
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Webhooks
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
import { verifyWebhook } from "@oryksa/sdk";
|
|
113
|
+
app.post("/oryksa-webhook", express.raw({ type: "application/json" }), async (req, res) => {
|
|
114
|
+
const event = await verifyWebhook(req.body, req.get("ORYKSA-Signature"), process.env.ORYKSA_WEBHOOK_SECRET);
|
|
115
|
+
if (event.type === "booking.created") { /* save it */ }
|
|
116
|
+
res.sendStatus(200);
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Errors
|
|
121
|
+
|
|
122
|
+
Every failed call throws `OryksaError` with `status`, `code` (for example `interaction_limit_reached`, `rate_limited`, `plan_required`) and `message`.
|
|
123
|
+
|
|
124
|
+
## About the author
|
|
125
|
+
|
|
126
|
+
**Weslley Harakawa** - Founder of ORYKSA AI. Based in Lisbon, Portugal. Specialties: artificial intelligence, web and mobile development, blockchain tokenization. Education: University of the People.
|
|
127
|
+
|
|
128
|
+
- LinkedIn: https://www.linkedin.com/in/weslleyharakawa/
|
|
129
|
+
- ORYKSA AI Employees: https://oryksa.com (X: https://x.com/oryksa, Instagram: https://www.instagram.com/oryksaai, YouTube: https://www.youtube.com/@ORYKSA)
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
MIT License · ORYKSA AI Employees · W8 Atlantic Unipessoal Lda
|
package/README.pt.md
CHANGED
|
@@ -1,91 +1,133 @@
|
|
|
1
|
-
<p align="center"><img src="https://app.oryksa.com/static/oryksa_logo.png" width="300" alt="ORYKSA"></p>
|
|
2
|
-
|
|
3
|
-
# @oryksa/sdk
|
|
4
|
-
|
|
5
|
-
[](README.md) [](README.pt.md) [](README.es.md) [](README.fr.md)
|
|
6
|
-
|
|
7
|
-
<p align="center"><a href="https://developer.oryksa.com/pt/sdks"><img src="https://developer.oryksa.com/assets/img/sdk/oryksa-sdks-pt.gif" width="760" alt="SDKs ORYKSA: o chat e a voz da IA no iOS, Android, Flutter, React Native e na web"></a></p>
|
|
8
|
-
|
|
9
|
-
SDK oficial de JavaScript e TypeScript da **ORYKSA AI Employees**: põe um colaborador de IA que já conhece o negócio dentro da tua app web, do teu backend Node ou da tua app de secretária Electron. O mesmo cérebro do WhatsApp e do chat do site, em texto e voz.
|
|
10
|
-
|
|
11
|
-
- Documentação: https://developer.oryksa.com
|
|
12
|
-
- API: `https://api.oryksa.com/v1`
|
|
13
|
-
|
|
14
|
-
## Capturas de ecrã
|
|
15
|
-
|
|
16
|
-
<p align="center"><img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_chat_pt.png" width="420" alt="Chat"> <img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_theme_pt.png" width="420" alt="Chat com o tema do README"></p>
|
|
17
|
-
|
|
18
|
-
Uma página de loja com `mountChat`, captada pelo CI no Chrome com uma conta de teste da ORYKSA (`test/shots.html`): cores de origem à esquerda e, à direita, o código de *Cores e tema*, mais abaixo.
|
|
19
|
-
|
|
20
|
-
## Instalar
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm install @oryksa/sdk
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Servidor (chave secreta)
|
|
27
|
-
|
|
28
|
-
```js
|
|
29
|
-
import { Oryksa } from "@oryksa/sdk";
|
|
30
|
-
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY); // developer.oryksa.com > Keys
|
|
31
|
-
|
|
32
|
-
const r = await oryksa.chat({ message: "Are you open on Saturday?" });
|
|
33
|
-
console.log(r.reply, r.conversation_id);
|
|
34
|
-
|
|
35
|
-
// Teach the AI employee about your app (e.g. on every release)
|
|
36
|
-
await oryksa.learnApp({
|
|
37
|
-
name: "FitTrack",
|
|
38
|
-
description: "Fitness app to log workouts and follow training plans.",
|
|
39
|
-
screens: [{ title: "Workouts", content: "Tap + to log a workout." }],
|
|
40
|
-
faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## Na app (token de sessão, nunca a chave secreta)
|
|
45
|
-
|
|
46
|
-
```js
|
|
47
|
-
// your server
|
|
48
|
-
app.get("/oryksa-token", requireLogin, async (req, res) => {
|
|
49
|
-
const s = await oryksa.createSession({ conversationId: "user-" + req.user.id, customerName: req.user.firstName });
|
|
50
|
-
res.json({ token: s.client_token });
|
|
51
|
-
});
|
|
52
|
-
|
|
53
|
-
// your web app
|
|
54
|
-
import { OryksaClient, mountChat } from "@oryksa/sdk";
|
|
55
|
-
const client = new OryksaClient({ getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token });
|
|
56
|
-
mountChat({ client, lang: "en" }); // ready-made chat UI
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
##
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
```js
|
|
64
|
-
mountChat({
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
1
|
+
<p align="center"><img src="https://app.oryksa.com/static/oryksa_logo.png" width="300" alt="ORYKSA"></p>
|
|
2
|
+
|
|
3
|
+
# @oryksa/sdk
|
|
4
|
+
|
|
5
|
+
[](README.md) [](README.pt.md) [](README.es.md) [](README.fr.md)
|
|
6
|
+
|
|
7
|
+
<p align="center"><a href="https://developer.oryksa.com/pt/sdks"><img src="https://developer.oryksa.com/assets/img/sdk/oryksa-sdks-pt.gif" width="760" alt="SDKs ORYKSA: o chat e a voz da IA no iOS, Android, Flutter, React Native e na web"></a></p>
|
|
8
|
+
|
|
9
|
+
SDK oficial de JavaScript e TypeScript da **ORYKSA AI Employees**: põe um colaborador de IA que já conhece o negócio dentro da tua app web, do teu backend Node ou da tua app de secretária Electron. O mesmo cérebro do WhatsApp e do chat do site, em texto e voz.
|
|
10
|
+
|
|
11
|
+
- Documentação: https://developer.oryksa.com
|
|
12
|
+
- API: `https://api.oryksa.com/v1`
|
|
13
|
+
|
|
14
|
+
## Capturas de ecrã
|
|
15
|
+
|
|
16
|
+
<p align="center"><img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_chat_pt.png" width="420" alt="Chat"> <img src="https://raw.githubusercontent.com/oryksa/oryksa-js/main/docs/screenshots/js_theme_pt.png" width="420" alt="Chat com o tema do README"></p>
|
|
17
|
+
|
|
18
|
+
Uma página de loja com `mountChat`, captada pelo CI no Chrome com uma conta de teste da ORYKSA (`test/shots.html`): cores de origem à esquerda e, à direita, o código de *Cores e tema*, mais abaixo.
|
|
19
|
+
|
|
20
|
+
## Instalar
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install @oryksa/sdk
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Servidor (chave secreta)
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
import { Oryksa } from "@oryksa/sdk";
|
|
30
|
+
const oryksa = new Oryksa(process.env.ORYKSA_API_KEY); // developer.oryksa.com > Keys
|
|
31
|
+
|
|
32
|
+
const r = await oryksa.chat({ message: "Are you open on Saturday?" });
|
|
33
|
+
console.log(r.reply, r.conversation_id);
|
|
34
|
+
|
|
35
|
+
// Teach the AI employee about your app (e.g. on every release)
|
|
36
|
+
await oryksa.learnApp({
|
|
37
|
+
name: "FitTrack",
|
|
38
|
+
description: "Fitness app to log workouts and follow training plans.",
|
|
39
|
+
screens: [{ title: "Workouts", content: "Tap + to log a workout." }],
|
|
40
|
+
faq: [{ question: "How do I cancel Premium?", answer: "Settings > Subscription > Cancel." }],
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Na app (token de sessão, nunca a chave secreta)
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
// your server
|
|
48
|
+
app.get("/oryksa-token", requireLogin, async (req, res) => {
|
|
49
|
+
const s = await oryksa.createSession({ conversationId: "user-" + req.user.id, customerName: req.user.firstName });
|
|
50
|
+
res.json({ token: s.client_token });
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// your web app
|
|
54
|
+
import { OryksaClient, mountChat } from "@oryksa/sdk";
|
|
55
|
+
const client = new OryksaClient({ getToken: async () => (await fetch("/oryksa-token").then(r => r.json())).token });
|
|
56
|
+
mountChat({ client, lang: "en" }); // ready-made chat UI
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Links com botão Abrir (0.1.5)
|
|
60
|
+
|
|
61
|
+
Os links que a IA dá ficam clicáveis no chat (endereços web e e-mails), e cada link web ganha um cartão por baixo da resposta com a foto e o título da página e um botão **Abrir** (as páginas do teu próprio site, os domínios do teu chat do site; outros sites mostram o endereço). Passa `onLink` para abrir as tuas próprias páginas, por exemplo a página do produto: devolve true quando a tua app o abriu, false para o abrir num separador novo.
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
mountChat({
|
|
65
|
+
client, lang: "pt",
|
|
66
|
+
onLink: (url) => {
|
|
67
|
+
const id = myProductIdOf(url); // as tuas rotas
|
|
68
|
+
if (!id) return false;
|
|
69
|
+
router.push("/product/" + id);
|
|
70
|
+
return true;
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`client.linkPreview(url)` dá o título e a foto de um link (`null` quando não se consegue ler); `linksIn(text)` e `withoutLinks(text)` também são exportados.
|
|
76
|
+
|
|
77
|
+
## Anexar uma foto ou um documento (0.1.5)
|
|
78
|
+
|
|
79
|
+
O chat do `mountChat` tem um botão de anexar: foto da galeria, câmara (telemóveis e tablets) ou documento (PDF, Word, texto, CSV). As fotos são reduzidas antes de seguir (até 2 MB); documentos até 8 MB. A IA vê a foto ou lê o documento. Desliga com `attachments: false`. Por código: `client.send(texto, { image: { base64, mime } })` ou `{ file: { base64, name, mime } }`.
|
|
80
|
+
|
|
81
|
+
## As tuas funções de IA: `ai` (0.1.5)
|
|
82
|
+
|
|
83
|
+
Põe a IA a fazer o que a tua app ou site precisa (ler uma foto, extrair dados, classificar, traduzir, escrever) e paga com interações ORYKSA: 1 por resposta. O teu prompt e o teu JSON Schema ficam no teu código; basta o token de sessão (nunca leves a chave secreta). Não cria conversa na tua caixa.
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
const r = await client.ai({
|
|
87
|
+
instructions: "Read the tyre on the photo: brand, model and size exactly as written on the sidewall. " +
|
|
88
|
+
"If the size is not legible, readable=false and size=null. Never invent.",
|
|
89
|
+
images: [{ base64: photoBase64, mime: "image/jpeg" }], // resized to 1600 px
|
|
90
|
+
schema: {
|
|
91
|
+
type: "object",
|
|
92
|
+
properties: { readable: { type: "boolean" }, brand: { type: ["string", "null"] }, size: { type: ["string", "null"] } },
|
|
93
|
+
required: ["readable", "brand", "size"],
|
|
94
|
+
},
|
|
95
|
+
});
|
|
96
|
+
if (r.json?.readable) showProducts(r.json.size);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`r.text` tem a resposta em texto, `r.json` o objeto (com schema) e `r.interactionsSpent` as interações gastas. Quando as interações do plano acabam, a chamada falha com `OryksaError` status 402.
|
|
100
|
+
|
|
101
|
+
## Cores e tema
|
|
102
|
+
|
|
103
|
+
O `mountChat` aceita três cores como texto CSS: `accent` (botões, balões do visitante, ligações), `ink` (texto principal) e `soft` (balões da IA). As que faltarem mantêm o valor por omissão (`#5B57E0`, `#161B3D` e `#EEEBFB`). O `position` (`"left"` ou `"right"`) escolhe o lado do ecrã.
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
mountChat({ client, lang: "en", accent: "#0E8A6B", ink: "#10281F", soft: "#E3F5EE" });
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Webhooks
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
import { verifyWebhook } from "@oryksa/sdk";
|
|
113
|
+
app.post("/oryksa-webhook", express.raw({ type: "application/json" }), async (req, res) => {
|
|
114
|
+
const event = await verifyWebhook(req.body, req.get("ORYKSA-Signature"), process.env.ORYKSA_WEBHOOK_SECRET);
|
|
115
|
+
if (event.type === "booking.created") { /* save it */ }
|
|
116
|
+
res.sendStatus(200);
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Erros
|
|
121
|
+
|
|
122
|
+
Cada chamada falhada lança `OryksaError` com `status`, `code` (por exemplo `interaction_limit_reached`, `rate_limited`, `plan_required`) e `message`.
|
|
123
|
+
|
|
124
|
+
## Sobre o autor
|
|
125
|
+
|
|
126
|
+
**Weslley Harakawa** - Fundador da ORYKSA AI. Em Lisboa, Portugal. Especialidades: inteligência artificial, desenvolvimento web e mobile, tokenização em blockchain. Formação: University of the People.
|
|
127
|
+
|
|
128
|
+
- LinkedIn: https://www.linkedin.com/in/weslleyharakawa/
|
|
129
|
+
- ORYKSA AI Employees: https://oryksa.com (X: https://x.com/oryksa, Instagram: https://www.instagram.com/oryksaai, YouTube: https://www.youtube.com/@ORYKSA)
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
MIT License · ORYKSA AI Employees · W8 Atlantic Unipessoal Lda
|
package/package.json
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@oryksa/sdk",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "ORYKSA AI Employees SDK: chat API, knowledge (Brain), webhooks and an in-app chat for web, Node and Electron.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"main": "src/index.js",
|
|
7
|
-
"module": "src/index.js",
|
|
8
|
-
"types": "src/index.d.ts",
|
|
9
|
-
"exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js" } },
|
|
10
|
-
"files": ["src", "README.md", "LICENSE"],
|
|
11
|
-
"engines": { "node": ">=18" },
|
|
12
|
-
"sideEffects": false,
|
|
13
|
-
"scripts": { "test": "node test/live.test.js" },
|
|
14
|
-
"keywords": ["oryksa", "ai", "chatbot", "customer-support", "ai-agent", "whatsapp", "mcp", "sdk"],
|
|
15
|
-
"homepage": "https://developer.oryksa.com",
|
|
16
|
-
"repository": { "type": "git", "url": "https://github.com/oryksa/oryksa-js" },
|
|
17
|
-
"author": "Weslley Harakawa (https://github.com/WeslleyHarakawa)",
|
|
18
|
-
"license": "MIT"
|
|
19
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@oryksa/sdk",
|
|
3
|
+
"version": "0.1.5",
|
|
4
|
+
"description": "ORYKSA AI Employees SDK: chat API, knowledge (Brain), webhooks and an in-app chat for web, Node and Electron.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "src/index.js",
|
|
7
|
+
"module": "src/index.js",
|
|
8
|
+
"types": "src/index.d.ts",
|
|
9
|
+
"exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js" } },
|
|
10
|
+
"files": ["src", "README.md", "LICENSE"],
|
|
11
|
+
"engines": { "node": ">=18" },
|
|
12
|
+
"sideEffects": false,
|
|
13
|
+
"scripts": { "test": "node test/links.test.js && node test/attach.test.js && node test/ai.test.js && node test/live.test.js", "test:links": "node test/links.test.js", "test:attach": "node test/attach.test.js", "test:ai": "node test/ai.test.js" },
|
|
14
|
+
"keywords": ["oryksa", "ai", "chatbot", "customer-support", "ai-agent", "whatsapp", "mcp", "sdk"],
|
|
15
|
+
"homepage": "https://developer.oryksa.com",
|
|
16
|
+
"repository": { "type": "git", "url": "https://github.com/oryksa/oryksa-js" },
|
|
17
|
+
"author": "Weslley Harakawa (https://github.com/WeslleyHarakawa)",
|
|
18
|
+
"license": "MIT"
|
|
19
|
+
}
|
package/src/index.d.ts
CHANGED
|
@@ -77,16 +77,105 @@ export interface AgentInfo {
|
|
|
77
77
|
voice_replies: boolean; conversation_id: string;
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
+
/** Title and picture of a link of the business's own site (OryksaClient.linkPreview). */
|
|
81
|
+
export interface LinkPreview {
|
|
82
|
+
object: "link_preview";
|
|
83
|
+
url: string;
|
|
84
|
+
/** Title of the page (empty for other sites). */
|
|
85
|
+
title: string;
|
|
86
|
+
/** Picture of the page (empty when it has none). */
|
|
87
|
+
image: string;
|
|
88
|
+
/** Name of the site. */
|
|
89
|
+
site: string;
|
|
90
|
+
/** Price, when the page says it (shops). */
|
|
91
|
+
price: string;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* What your app does with a link the AI gave (a product, a service, a page). Return true when your app
|
|
96
|
+
* opened it itself (for example its own product page); return false and it opens in a new tab.
|
|
97
|
+
*/
|
|
98
|
+
export type LinkHandler = (url: string) => boolean;
|
|
99
|
+
|
|
100
|
+
/** A photo from the customer (JPEG, PNG or WebP, up to 2 MB). The AI looks at it. */
|
|
101
|
+
export interface ChatImage { base64: string; mime?: string }
|
|
102
|
+
|
|
103
|
+
/** A document from the customer (PDF, Word, text or CSV, up to 8 MB). The AI reads it. */
|
|
104
|
+
export interface ChatFile { base64: string; name: string; mime?: string }
|
|
105
|
+
|
|
106
|
+
/** Options of OryksaClient.ai: your prompt and your JSON Schema live in your app. */
|
|
107
|
+
export interface AiOptions {
|
|
108
|
+
instructions?: string;
|
|
109
|
+
input?: string;
|
|
110
|
+
/** Up to 4 photos (about 1.5 MB each; resize to 1600 px). */
|
|
111
|
+
images?: ChatImage[];
|
|
112
|
+
/** A JSON Schema: the answer comes back in `json`. */
|
|
113
|
+
schema?: object;
|
|
114
|
+
maxTokens?: number;
|
|
115
|
+
temperature?: number;
|
|
116
|
+
}
|
|
117
|
+
/** The answer of OryksaClient.ai. */
|
|
118
|
+
export interface AiResult {
|
|
119
|
+
text: string;
|
|
120
|
+
json: Record<string, unknown> | null;
|
|
121
|
+
interactionsSpent: number;
|
|
122
|
+
interactionsRemaining: number | null;
|
|
123
|
+
}
|
|
124
|
+
export declare function aiBody(opts: AiOptions): Record<string, unknown>;
|
|
125
|
+
export declare function aiResult(d: unknown): AiResult;
|
|
126
|
+
|
|
80
127
|
export declare class OryksaClient {
|
|
81
128
|
constructor(opts: { token?: string; getToken?: () => Promise<string>; baseUrl?: string; fetch?: typeof fetch; timeoutMs?: number });
|
|
82
129
|
agent(): Promise<AgentInfo>;
|
|
83
|
-
|
|
130
|
+
/** image: sent as image_base64 / image_mime; file: sent as file_base64 / file_name / file_mime. */
|
|
131
|
+
send(message: string, opts?: { image?: ChatImage; file?: ChatFile }): Promise<ChatReply>;
|
|
84
132
|
messages(): Promise<{ id: string; messages: Message[] }>;
|
|
133
|
+
/** Title and picture of a link the AI gave (only the pages of the business's own site); null when it cannot be read, never throws. */
|
|
134
|
+
linkPreview(url: string): Promise<LinkPreview | null>;
|
|
135
|
+
/** An AI task of your own app, counted as ORYKSA interactions (1 per answer). Never creates a conversation. */
|
|
136
|
+
ai(opts: AiOptions): Promise<AiResult>;
|
|
85
137
|
}
|
|
86
138
|
|
|
87
139
|
export declare function mountChat(opts: {
|
|
88
140
|
client: OryksaClient; lang?: "en" | "pt" | "br" | "es"; position?: "left" | "right";
|
|
89
141
|
accent?: string; ink?: string; soft?: string; open?: boolean;
|
|
90
|
-
|
|
142
|
+
/** What your app does with a link the AI gave: return true when your app opened it, false to open it in a new tab. */
|
|
143
|
+
onLink?: LinkHandler;
|
|
144
|
+
/** Shows the attach button (photo library, camera on phones, document). Default true. */
|
|
145
|
+
attachments?: boolean;
|
|
146
|
+
}): { open(): void; close(): void; send(text: string, att?: { image?: ChatImage; file?: ChatFile }): Promise<void>; destroy(): void };
|
|
147
|
+
|
|
148
|
+
export type AttachResult = { image: ChatImage } | { file: ChatFile } | { error: "big" | "failed" };
|
|
149
|
+
|
|
150
|
+
/** 2 MB: the largest photo the chat sends. */
|
|
151
|
+
export declare const MAX_PHOTO_BYTES: number;
|
|
152
|
+
/** 8 MB: the largest document the chat sends. */
|
|
153
|
+
export declare const MAX_FILE_BYTES: number;
|
|
154
|
+
/** The type of a file from its name. */
|
|
155
|
+
export declare function mimeOf(name: string): string;
|
|
156
|
+
/** How many bytes a base64 text holds. */
|
|
157
|
+
export declare function base64Bytes(b64: string): number;
|
|
158
|
+
/** The size of a photo with its longest side at most maxSide (1600 by default), never larger. */
|
|
159
|
+
export declare function scaledSize(w: number, h: number, maxSide?: number): { width: number; height: number };
|
|
160
|
+
/** A photo as what the chat sends ({ error: "big" } above 2 MB). */
|
|
161
|
+
export declare function photoAttachment(p: { base64: string; mime?: string } | null): AttachResult;
|
|
162
|
+
/** A document as what the chat sends: pictures up to 2 MB as a photo, the rest as a file up to 8 MB. */
|
|
163
|
+
export declare function documentAttachment(d: { base64?: string; name?: string; mime?: string; tooBig?: boolean } | null): AttachResult;
|
|
164
|
+
/** Browser: a picture File as a JPEG of at most 1600 pixels, 80%. */
|
|
165
|
+
export declare function photoFromFile(file: Blob, maxSide?: number, quality?: number): Promise<{ base64: string; mime: string }>;
|
|
166
|
+
/** Browser: a document File as { base64, name, mime } (or { tooBig: true } above 8 MB). */
|
|
167
|
+
export declare function documentFromFile(file: File): Promise<{ base64?: string; name: string; mime?: string; tooBig?: boolean }>;
|
|
168
|
+
|
|
169
|
+
/** The distinct web links of text, in order, without the final punctuation (at most max, 3 by default). */
|
|
170
|
+
export declare function linksIn(text: string, max?: number): string[];
|
|
171
|
+
|
|
172
|
+
/** text without its web links (what a voice screen shows while she speaks). */
|
|
173
|
+
export declare function withoutLinks(text: string): string;
|
|
174
|
+
|
|
175
|
+
/** text as parts: url only on the links (web, and e-mail as mailto:). */
|
|
176
|
+
export declare function linkParts(text: string): { text: string; url: string | null }[];
|
|
177
|
+
|
|
178
|
+
/** Opens a link: handler first (true = your app opened it), then a new tab (window.open, noopener). */
|
|
179
|
+
export declare function openLink(url: string, handler?: LinkHandler): void;
|
|
91
180
|
|
|
92
181
|
export default Oryksa;
|