@oryksa/sdk 0.1.3 → 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 -0
- package/README.fr.md +133 -0
- package/README.md +133 -75
- package/README.pt.md +133 -0
- package/package.json +19 -19
- package/src/index.d.ts +181 -92
- package/src/index.js +719 -325
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
|
@@ -1,92 +1,181 @@
|
|
|
1
|
-
export declare const VERSION: string;
|
|
2
|
-
|
|
3
|
-
export declare class OryksaError extends Error {
|
|
4
|
-
status: number;
|
|
5
|
-
code: string;
|
|
6
|
-
upgrade_url?: string;
|
|
7
|
-
retry_after?: number;
|
|
8
|
-
}
|
|
9
|
-
|
|
10
|
-
export interface ChatReply {
|
|
11
|
-
object: "chat_reply";
|
|
12
|
-
conversation_id: string;
|
|
13
|
-
status: "replied" | "pending";
|
|
14
|
-
reply: string | null;
|
|
15
|
-
hint?: string;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
export interface Message { role: "user" | "assistant"; content: string }
|
|
19
|
-
|
|
20
|
-
export interface ServerOptions {
|
|
21
|
-
baseUrl?: string;
|
|
22
|
-
fetch?: typeof fetch;
|
|
23
|
-
timeoutMs?: number;
|
|
24
|
-
/** Only for local tools. The secret key must never reach end users. */
|
|
25
|
-
dangerouslyAllowBrowser?: boolean;
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
export interface AppDescription {
|
|
29
|
-
name: string;
|
|
30
|
-
description?: string;
|
|
31
|
-
url?: string;
|
|
32
|
-
agentName?: string;
|
|
33
|
-
languages?: string[];
|
|
34
|
-
services?: string[];
|
|
35
|
-
screens?: { title: string; content: string; url?: string }[];
|
|
36
|
-
faq?: { question: string; answer: string }[];
|
|
37
|
-
settings?: Record<string, unknown>;
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
export type WebhookEvent = "message.replied" | "booking.created" | "limit.reached" | "knowledge.updated" | "*";
|
|
41
|
-
|
|
42
|
-
export declare class Oryksa {
|
|
43
|
-
constructor(apiKey: string, opts?: ServerOptions);
|
|
44
|
-
account(): Promise<any>;
|
|
45
|
-
chat(p: { message: string; conversationId?: string; customerName?: string }): Promise<ChatReply>;
|
|
46
|
-
conversations(p?: { limit?: number }): Promise<{ object: "list"; data: any[] }>;
|
|
47
|
-
conversation(id: string): Promise<{ object: "conversation"; id: string; messages: Message[] }>;
|
|
48
|
-
readonly agent: {
|
|
49
|
-
update(fields: Record<string, unknown>): Promise<{ object: "agent"; updated: string[] }>;
|
|
50
|
-
appearance(fields: Record<string, unknown>): Promise<{ object: "agent_appearance"; updated: string[] }>;
|
|
51
|
-
};
|
|
52
|
-
readonly knowledge: {
|
|
53
|
-
get(): Promise<any>;
|
|
54
|
-
setPages(p: { pages: { title?: string; url?: string; content: string }[]; businessSummary?: string; siteUrl?: string }): Promise<any>;
|
|
55
|
-
crawl(p: { url: string; maxPages?: number }): Promise<any>;
|
|
56
|
-
addFaq(items: { question: string; answer: string }[]): Promise<{ added: number; updated: number }>;
|
|
57
|
-
};
|
|
58
|
-
readonly widget: {
|
|
59
|
-
snippet(p?: { framework?: string; lang?: string; position?: "left" | "right" }): Promise<any>;
|
|
60
|
-
setDomains(domains: string[]): Promise<any>;
|
|
61
|
-
};
|
|
62
|
-
readonly webhooks: {
|
|
63
|
-
list(): Promise<any>;
|
|
64
|
-
create(p: { url: string; events?: WebhookEvent[] }): Promise<any>;
|
|
65
|
-
delete(id: string): Promise<any>;
|
|
66
|
-
test(id: string): Promise<{ status: number; delivered: boolean }>;
|
|
67
|
-
};
|
|
68
|
-
createSession(p?: { conversationId?: string; customerName?: string; ttlMinutes?: number }): Promise<{ client_token: string; conversation_id: string; expires_at: string }>;
|
|
69
|
-
learnApp(app: AppDescription): Promise<any>;
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
export declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number }): Promise<{ id: string; type: string; created_at: string; data: any }>;
|
|
73
|
-
|
|
74
|
-
export interface AgentInfo {
|
|
75
|
-
name: string; business: string | null; gender: "female" | "male"; avatar: string;
|
|
76
|
-
greeting: Record<string, string>; suggestions: Record<string, string[]>; subtitle: Record<string, string>;
|
|
77
|
-
voice_replies: boolean; conversation_id: string;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
1
|
+
export declare const VERSION: string;
|
|
2
|
+
|
|
3
|
+
export declare class OryksaError extends Error {
|
|
4
|
+
status: number;
|
|
5
|
+
code: string;
|
|
6
|
+
upgrade_url?: string;
|
|
7
|
+
retry_after?: number;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export interface ChatReply {
|
|
11
|
+
object: "chat_reply";
|
|
12
|
+
conversation_id: string;
|
|
13
|
+
status: "replied" | "pending";
|
|
14
|
+
reply: string | null;
|
|
15
|
+
hint?: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface Message { role: "user" | "assistant"; content: string }
|
|
19
|
+
|
|
20
|
+
export interface ServerOptions {
|
|
21
|
+
baseUrl?: string;
|
|
22
|
+
fetch?: typeof fetch;
|
|
23
|
+
timeoutMs?: number;
|
|
24
|
+
/** Only for local tools. The secret key must never reach end users. */
|
|
25
|
+
dangerouslyAllowBrowser?: boolean;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface AppDescription {
|
|
29
|
+
name: string;
|
|
30
|
+
description?: string;
|
|
31
|
+
url?: string;
|
|
32
|
+
agentName?: string;
|
|
33
|
+
languages?: string[];
|
|
34
|
+
services?: string[];
|
|
35
|
+
screens?: { title: string; content: string; url?: string }[];
|
|
36
|
+
faq?: { question: string; answer: string }[];
|
|
37
|
+
settings?: Record<string, unknown>;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export type WebhookEvent = "message.replied" | "booking.created" | "limit.reached" | "knowledge.updated" | "*";
|
|
41
|
+
|
|
42
|
+
export declare class Oryksa {
|
|
43
|
+
constructor(apiKey: string, opts?: ServerOptions);
|
|
44
|
+
account(): Promise<any>;
|
|
45
|
+
chat(p: { message: string; conversationId?: string; customerName?: string }): Promise<ChatReply>;
|
|
46
|
+
conversations(p?: { limit?: number }): Promise<{ object: "list"; data: any[] }>;
|
|
47
|
+
conversation(id: string): Promise<{ object: "conversation"; id: string; messages: Message[] }>;
|
|
48
|
+
readonly agent: {
|
|
49
|
+
update(fields: Record<string, unknown>): Promise<{ object: "agent"; updated: string[] }>;
|
|
50
|
+
appearance(fields: Record<string, unknown>): Promise<{ object: "agent_appearance"; updated: string[] }>;
|
|
51
|
+
};
|
|
52
|
+
readonly knowledge: {
|
|
53
|
+
get(): Promise<any>;
|
|
54
|
+
setPages(p: { pages: { title?: string; url?: string; content: string }[]; businessSummary?: string; siteUrl?: string }): Promise<any>;
|
|
55
|
+
crawl(p: { url: string; maxPages?: number }): Promise<any>;
|
|
56
|
+
addFaq(items: { question: string; answer: string }[]): Promise<{ added: number; updated: number }>;
|
|
57
|
+
};
|
|
58
|
+
readonly widget: {
|
|
59
|
+
snippet(p?: { framework?: string; lang?: string; position?: "left" | "right" }): Promise<any>;
|
|
60
|
+
setDomains(domains: string[]): Promise<any>;
|
|
61
|
+
};
|
|
62
|
+
readonly webhooks: {
|
|
63
|
+
list(): Promise<any>;
|
|
64
|
+
create(p: { url: string; events?: WebhookEvent[] }): Promise<any>;
|
|
65
|
+
delete(id: string): Promise<any>;
|
|
66
|
+
test(id: string): Promise<{ status: number; delivered: boolean }>;
|
|
67
|
+
};
|
|
68
|
+
createSession(p?: { conversationId?: string; customerName?: string; customerEmail?: string; customerPhone?: string; ttlMinutes?: number }): Promise<{ client_token: string; conversation_id: string; expires_at: string }>;
|
|
69
|
+
learnApp(app: AppDescription): Promise<any>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, secret: string, opts?: { toleranceSeconds?: number }): Promise<{ id: string; type: string; created_at: string; data: any }>;
|
|
73
|
+
|
|
74
|
+
export interface AgentInfo {
|
|
75
|
+
name: string; business: string | null; gender: "female" | "male"; avatar: string;
|
|
76
|
+
greeting: Record<string, string>; suggestions: Record<string, string[]>; subtitle: Record<string, string>;
|
|
77
|
+
voice_replies: boolean; conversation_id: string;
|
|
78
|
+
}
|
|
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
|
+
|
|
127
|
+
export declare class OryksaClient {
|
|
128
|
+
constructor(opts: { token?: string; getToken?: () => Promise<string>; baseUrl?: string; fetch?: typeof fetch; timeoutMs?: number });
|
|
129
|
+
agent(): Promise<AgentInfo>;
|
|
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>;
|
|
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>;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
export declare function mountChat(opts: {
|
|
140
|
+
client: OryksaClient; lang?: "en" | "pt" | "br" | "es"; position?: "left" | "right";
|
|
141
|
+
accent?: string; ink?: string; soft?: string; open?: boolean;
|
|
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;
|
|
180
|
+
|
|
181
|
+
export default Oryksa;
|