oraku-sdk 1.0.0 → 1.1.0
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 +149 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# oraku-sdk
|
|
2
|
+
|
|
3
|
+
SDK for the Oraku engagement engine. Send activity events from your app, get back personalised push notifications driven by behavioural pattern detection.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install oraku-sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Setup
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import OrakuSDK from 'oraku-sdk'
|
|
19
|
+
|
|
20
|
+
const oraku = new OrakuSDK({
|
|
21
|
+
apiUrl: 'https://your-oraku-api.com',
|
|
22
|
+
apiKey: 'your-api-key'
|
|
23
|
+
})
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
| Option | Type | Description |
|
|
27
|
+
| -------- | ------ | ---------------------------------- |
|
|
28
|
+
| `apiUrl` | string | Base URL of your Oraku API instance |
|
|
29
|
+
| `apiKey` | string | Your project API key |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Methods
|
|
34
|
+
|
|
35
|
+
### `loadInformation(events)`
|
|
36
|
+
|
|
37
|
+
Sends activity events to the Oraku engine. The engine stitches events by user, runs pattern detectors (streaks, recurring behaviour, anomalies), and stores the results ready to be pulled as notifications.
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
await oraku.loadInformation([
|
|
41
|
+
{
|
|
42
|
+
externalRef: 'evt-001',
|
|
43
|
+
category: 'fitness',
|
|
44
|
+
subcategory: 'cardio',
|
|
45
|
+
log: '5km morning run',
|
|
46
|
+
createdAt: '2026-03-13T07:30:00Z',
|
|
47
|
+
meta: {
|
|
48
|
+
userId: 'user-123',
|
|
49
|
+
username: 'Emma'
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
])
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Event fields:**
|
|
56
|
+
|
|
57
|
+
| Field | Type | Description |
|
|
58
|
+
| ------------ | ----------------------- | --------------------------------------------------------------------------- |
|
|
59
|
+
| `externalRef`| string | Unique ID for this event — used for deduplication |
|
|
60
|
+
| `category` | string | Top-level activity type (e.g. `fitness`, `childcare`, `puzzle`) |
|
|
61
|
+
| `subcategory`| string | More specific type (e.g. `cardio`, `pickup`, `crossword`) |
|
|
62
|
+
| `log` | string | Human-readable description of what happened |
|
|
63
|
+
| `createdAt` | string (ISO 8601) | When the event occurred — critical for streak and pattern detection |
|
|
64
|
+
| `meta` | object | Arbitrary metadata. `meta.userId` is required for per-user routing. `meta.username` is used in notification copy. |
|
|
65
|
+
|
|
66
|
+
> **Important:** `meta.userId` is how the engine groups events per user. All events for the same user must share the same `meta.userId`. Without it, events are grouped under `unknown`.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
### `generateEngagementPulls(filter, type, options?)`
|
|
71
|
+
|
|
72
|
+
Fetches notifications generated from the last `loadInformation` call, filtered to a specific user or category.
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
const notifications = await oraku.generateEngagementPulls(
|
|
76
|
+
{ externalRef: 'user-123' },
|
|
77
|
+
'notifications',
|
|
78
|
+
{ limit: 3 }
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
// ['You've hit a 7-day fitness streak — keep it going.', ...]
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Returns `string[]` — each string is a ready-to-send push notification.
|
|
85
|
+
|
|
86
|
+
**Filter:**
|
|
87
|
+
|
|
88
|
+
| Field | Type | Description |
|
|
89
|
+
| ------------ | ------ | ---------------------------------------- |
|
|
90
|
+
| `externalRef`| string | The `meta.userId` of the user to fetch for |
|
|
91
|
+
| `category` | string | Optional — filter by activity category |
|
|
92
|
+
|
|
93
|
+
**Options:**
|
|
94
|
+
|
|
95
|
+
| Field | Type | Description |
|
|
96
|
+
| ------- | ------ | ------------------------------------ |
|
|
97
|
+
| `limit` | number | Max number of notifications to return |
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
### `project.setSettings(settings)`
|
|
102
|
+
|
|
103
|
+
Stores a webhook URL for your project. When set, Oraku can push notifications to your endpoint instead of waiting to be polled.
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
await oraku.project.setSettings({
|
|
107
|
+
webhookUrl: 'https://yourapp.com/oraku-webhook',
|
|
108
|
+
webhookAuthKey: 'optional-secret'
|
|
109
|
+
})
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
| Field | Type | Description |
|
|
113
|
+
| --------------- | ------ | ---------------------------------------------- |
|
|
114
|
+
| `webhookUrl` | string | URL Oraku will POST notifications to |
|
|
115
|
+
| `webhookAuthKey`| string | Optional secret sent in the request header |
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
### `project.setCron(cron)`
|
|
120
|
+
|
|
121
|
+
Configures a schedule for Oraku to automatically run the pipeline and push notifications on a recurring basis.
|
|
122
|
+
|
|
123
|
+
```ts
|
|
124
|
+
await oraku.project.setCron({
|
|
125
|
+
cron: '0 9 * * *',
|
|
126
|
+
type: 'daily'
|
|
127
|
+
})
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
| Field | Type | Description |
|
|
131
|
+
| ------ | ----------------------------- | ---------------------------------- |
|
|
132
|
+
| `cron` | string | Cron expression for the schedule |
|
|
133
|
+
| `type` | `daily` \| `weekly` \| `monthly` | Schedule category |
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## How it works
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
Your app
|
|
141
|
+
→ loadInformation(events)
|
|
142
|
+
→ events grouped by meta.userId
|
|
143
|
+
→ pattern detectors run per user (streaks, recurring patterns, anomalies)
|
|
144
|
+
→ findings converted to personalised notifications via LLM
|
|
145
|
+
→ generateEngagementPulls({ externalRef: userId })
|
|
146
|
+
→ returns that user's notifications as plain strings
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Notifications are scoped per user — each user only receives notifications based on their own activity history. The engine handles all detection and copy generation; you just send events and display the output.
|