@mindstudio-ai/agent 0.1.176 → 0.1.178
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/CHANGELOG.md +14 -0
- package/dist/analytics/index.d.ts +384 -0
- package/dist/auth/index.d.ts +113 -0
- package/dist/browser/index.d.ts +332 -0
- package/dist/cli.js +29 -29
- package/dist/client.d.ts +767 -0
- package/dist/config.d.ts +13 -0
- package/dist/context.d.ts +125 -0
- package/dist/datasources/index.d.ts +52 -0
- package/dist/datasources/source.d.ts +1074 -0
- package/dist/db/aggregate.d.ts +101 -0
- package/dist/db/index.d.ts +280 -0
- package/dist/db/mutation.d.ts +65 -0
- package/dist/db/predicate.d.ts +85 -0
- package/dist/db/query.d.ts +233 -0
- package/dist/db/raw.d.ts +36 -0
- package/dist/db/readBatching.d.ts +36 -0
- package/dist/db/scanHints.d.ts +8 -0
- package/dist/db/sql.d.ts +136 -0
- package/dist/db/table.d.ts +146 -0
- package/dist/db/time.d.ts +17 -0
- package/dist/db/types.d.ts +237 -0
- package/dist/db-ws.d.ts +35 -0
- package/dist/email/index.d.ts +396 -0
- package/dist/errors.d.ts +34 -0
- package/dist/events/index.d.ts +127 -0
- package/dist/files/index.d.ts +62 -0
- package/dist/files/store.d.ts +244 -0
- package/dist/generated/metadata.d.ts +8 -0
- package/dist/generated/snippets.d.ts +8 -0
- package/dist/generated/steps.d.ts +2745 -0
- package/dist/generated/types.d.ts +4234 -0
- package/dist/http.d.ts +22 -0
- package/dist/index.d.ts +59 -13329
- package/dist/index.js +17 -17
- package/dist/index.js.map +7 -1
- package/dist/jewel/index.d.ts +325 -0
- package/dist/mapper/index.d.ts +229 -0
- package/dist/rate-limit.d.ts +25 -0
- package/dist/reader/index.d.ts +170 -0
- package/dist/respond.d.ts +68 -0
- package/dist/task/index.d.ts +18 -0
- package/dist/task/local.d.ts +48 -0
- package/dist/task/schema.d.ts +120 -0
- package/dist/task/types.d.ts +203 -0
- package/dist/types.d.ts +591 -0
- package/dist/voice/index.d.ts +87 -0
- package/llms.txt +2 -2
- package/package.json +6 -12
- package/dist/postinstall.js +0 -12115
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,20 @@ What changed in `@mindstudio-ai/agent`, newest first, each version under its own
|
|
|
4
4
|
|
|
5
5
|
Versions before 0.1.163 aren't recorded here.
|
|
6
6
|
|
|
7
|
+
## 0.1.178
|
|
8
|
+
|
|
9
|
+
### Changed behavior
|
|
10
|
+
|
|
11
|
+
- `generateSound`'s default model is `elevenlabs-sound_v3`, ElevenLabs' SFX v3, in place of `elevenlabs-sound_v2`, which ElevenLabs removes on 2027-03-01. It takes the same settings at the same price, and the usage notes say so. A step that names `elevenlabs-sound_v2` runs as itself until then, and as v3 after. App code isn't affected.
|
|
12
|
+
- `generate3dModel`'s usage notes no longer list `wavespeed-tripo3d-v2.5` or `wavespeed-sam-3d-objects`, whose endpoints WaveSpeed took down. A step that names either runs on `wavespeed-tripo3d-h3.1`, from the same `image`; SAM 3D's `mask_images` are dropped. Check: code that names either model, if it counted on SAM 3D's masks.
|
|
13
|
+
|
|
14
|
+
## 0.1.177
|
|
15
|
+
|
|
16
|
+
### Changed behavior
|
|
17
|
+
|
|
18
|
+
- Installing the package runs no script. It used to run a postinstall that started sign-in after an interactive global install (`npm install -g @mindstudio-ai/agent`); after one now, `mindstudio login`, or `mindstudio` with nothing after it, signs in. Nothing changes for an app that depends on the package. Check: a setup script that counted on the install to sign in runs `mindstudio login` after it.
|
|
19
|
+
- Built with esbuild and the TypeScript compiler rather than tsup. The types are a `.d.ts` file for each source file, behind the same `types` path, in place of one combined file. App code isn't affected.
|
|
20
|
+
|
|
7
21
|
## 0.1.176
|
|
8
22
|
|
|
9
23
|
### Changed behavior
|
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `analytics` namespace — read the app's OWN traffic and event analytics
|
|
3
|
+
* from method code. The platform auto-tracks pageviews (and custom events via
|
|
4
|
+
* the frontend's `analytics.track()`); this is the read side, so an app can
|
|
5
|
+
* correlate real traffic with its own data — lifetime views next to each blog
|
|
6
|
+
* post, "12 people reading now", conversion events beside the records that
|
|
7
|
+
* produced them.
|
|
8
|
+
*
|
|
9
|
+
* One general read, `query()`, shaped like the Plausible/GA4 family:
|
|
10
|
+
*
|
|
11
|
+
* ```ts
|
|
12
|
+
* import { analytics } from '@mindstudio-ai/agent';
|
|
13
|
+
*
|
|
14
|
+
* // Lifetime pageviews + unique visitors per page — top 10, all history.
|
|
15
|
+
* const top = await analytics.query({
|
|
16
|
+
* metrics: ['pageviews', 'visitors'],
|
|
17
|
+
* dimensions: ['path'],
|
|
18
|
+
* dateRange: 'all',
|
|
19
|
+
* limit: 10,
|
|
20
|
+
* });
|
|
21
|
+
* // top.results[0] → { dimensions: { path: '/post/hello' },
|
|
22
|
+
* // metrics: { pageviews: 4210, visitors: 1830 } }
|
|
23
|
+
*
|
|
24
|
+
* // Daily views for one post, full history.
|
|
25
|
+
* const series = await analytics.query({
|
|
26
|
+
* metrics: ['pageviews'],
|
|
27
|
+
* dimensions: ['time'],
|
|
28
|
+
* granularity: 'day',
|
|
29
|
+
* filters: [['is', 'path', ['/post/hello']]],
|
|
30
|
+
* dateRange: 'all',
|
|
31
|
+
* });
|
|
32
|
+
*
|
|
33
|
+
* // A whole page in one round trip — prefer this over a parallel burst.
|
|
34
|
+
* const [kpis, byPage, byCountry] = await analytics.batch([
|
|
35
|
+
* { metrics: ['pageviews', 'visits', 'visitors'], dateRange: '30d' },
|
|
36
|
+
* { metrics: ['pageviews'], dimensions: ['path'], dateRange: '30d' },
|
|
37
|
+
* { metrics: ['visitors'], dimensions: ['country'], dateRange: '30d' },
|
|
38
|
+
* ]);
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* Reads are rate limited per app (600/min; each query in a batch counts as
|
|
42
|
+
* one, and the SDK retries a single 429 automatically). Don't swallow
|
|
43
|
+
* `rate_limited` errors into empty data — surface them or retry.
|
|
44
|
+
*
|
|
45
|
+
* **How far back a query can look depends on its shape.** Queries whose
|
|
46
|
+
* filters are all `is` and touch at most ONE dimension read a rollup kept
|
|
47
|
+
* forever — full lifetime history, exact unique visitors. Cross-dimension
|
|
48
|
+
* intersections (`views of /post/x from mobile`), `is_not`, and `contains`
|
|
49
|
+
* scan raw events retained for 90 days; the server clamps the window and says
|
|
50
|
+
* so (`meta.source`, `meta.clamped`). Metrics a shape can't carry come back
|
|
51
|
+
* in `meta.metricsOmitted`, never as silent zeros. Time on page and scroll
|
|
52
|
+
* depth are lifetime per page; anything about whole visits (bounce rate,
|
|
53
|
+
* visit duration, entry and exit pages, a visit's first source) reads the
|
|
54
|
+
* raw events.
|
|
55
|
+
*
|
|
56
|
+
* The specials cover reads that aren't group-bys: `funnel()` (visits through
|
|
57
|
+
* ordered steps, and where they dropped off), `paths()` (where visits went
|
|
58
|
+
* next, and their commonest routes), `live()` (who's on the app right now),
|
|
59
|
+
* `sources()` (per-session first-source ranking, classified), `map()` (city
|
|
60
|
+
* points), `aiSources()` (AI-assistant referrals by vendor), and `crawlers.*`
|
|
61
|
+
* (bot/crawler ingestion). `funnel()` and `paths()` follow a visitor across
|
|
62
|
+
* the apps sharing this one's host: an app it mounts, or the app it's
|
|
63
|
+
* mounted under.
|
|
64
|
+
*
|
|
65
|
+
* Analytics is app-scoped and comes from production traffic — a method
|
|
66
|
+
* running in the dev sandbox reads the LIVE app's real data, which is what
|
|
67
|
+
* you want while building an admin view.
|
|
68
|
+
*/
|
|
69
|
+
/** @internal Transport bound by the client: POST /_internal/v2/analytics/<op>. */
|
|
70
|
+
export type AnalyticsTransport = (op: string, body: unknown) => Promise<any>;
|
|
71
|
+
/**
|
|
72
|
+
* Counts: `pageviews`, `visitors`, `visits`, `events`. Averages, `null` when
|
|
73
|
+
* there's nothing to average: `timeOnPage` (seconds a page was actively read,
|
|
74
|
+
* over the pages that reported), `scrollDepth` (% of the page, the deepest
|
|
75
|
+
* each page reached), `visitDuration` (seconds of active reading per visit)
|
|
76
|
+
* and `bounceRate` (% of visits with one pageview, no custom event and under
|
|
77
|
+
* ten seconds active).
|
|
78
|
+
*/
|
|
79
|
+
export type AnalyticsMetric = AnalyticsCountMetric | AnalyticsAverageMetric;
|
|
80
|
+
export type AnalyticsCountMetric = 'pageviews' | 'visitors' | 'visits' | 'events';
|
|
81
|
+
export type AnalyticsAverageMetric = 'timeOnPage' | 'scrollDepth' | 'visitDuration' | 'bounceRate';
|
|
82
|
+
/**
|
|
83
|
+
* What a row is grouped or filtered by. The `visit…`, `entryPath` and
|
|
84
|
+
* `exitPath` dimensions describe the whole visit a row belongs to: where it
|
|
85
|
+
* entered and left, and its first source and campaign. `prop:<key>` is a
|
|
86
|
+
* custom event's property (a key of letters, digits, `_`, `-` and `.`).
|
|
87
|
+
*/
|
|
88
|
+
export type AnalyticsDimension = 'path' | 'referrerHost' | 'sourceCategory' | 'country' | 'city' | 'deviceType' | 'browser' | 'os' | 'language' | 'visitorType' | 'utmSource' | 'utmMedium' | 'utmCampaign' | 'utmTerm' | 'utmContent' | 'eventName' | 'entryPath' | 'exitPath' | 'visitReferrerHost' | 'visitSourceCategory' | 'visitUtmSource' | 'visitUtmMedium' | 'visitUtmCampaign' | 'visitUtmTerm' | 'visitUtmContent' | `prop:${string}`;
|
|
89
|
+
/** A filter only, never a group: the visit includes this custom event. */
|
|
90
|
+
export type AnalyticsFilterOnlyDimension = 'visitEvent';
|
|
91
|
+
export type AnalyticsFilterOp = 'is' | 'is_not' | 'contains';
|
|
92
|
+
/**
|
|
93
|
+
* `[op, dimension, values]`. `is` matches any of the values; `is_not`
|
|
94
|
+
* excludes all of them (rows missing the dimension still match); `contains`
|
|
95
|
+
* is case-insensitive substring. Only `is` filters can be served from the
|
|
96
|
+
* lifetime rollup — the others read the 90-day event table. `city` filters
|
|
97
|
+
* take plain city names (matching any country) and always read the 90-day
|
|
98
|
+
* event table. A filter on a visit dimension keeps the rows of visits that
|
|
99
|
+
* match; `['is', 'visitEvent', ['signup']]` keeps those of visits that fired
|
|
100
|
+
* `signup`, so grouping them by `path` gives the pages that led to it.
|
|
101
|
+
*/
|
|
102
|
+
export type AnalyticsFilter = [
|
|
103
|
+
AnalyticsFilterOp,
|
|
104
|
+
AnalyticsDimension | AnalyticsFilterOnlyDimension,
|
|
105
|
+
string[]
|
|
106
|
+
];
|
|
107
|
+
export type AnalyticsGranularity = '5m' | 'hour' | 'day' | 'week' | 'month';
|
|
108
|
+
/** Shorthand ("30d", "all") or explicit `[startISO, endISO]`. Default "24h". */
|
|
109
|
+
export type AnalyticsDateRange = '1h' | '24h' | '7d' | '30d' | '90d' | 'all' | [string, string];
|
|
110
|
+
export interface AnalyticsQuerySpec {
|
|
111
|
+
/** At least one metric. */
|
|
112
|
+
metrics: AnalyticsMetric[];
|
|
113
|
+
/** At most one entity dimension OR `'time'` (not both, yet). */
|
|
114
|
+
dimensions?: (AnalyticsDimension | 'time')[];
|
|
115
|
+
/**
|
|
116
|
+
* Required when `'time'` is in dimensions. With `dateRange: 'all'` it is
|
|
117
|
+
* a minimum — the server coarsens automatically once the app's history
|
|
118
|
+
* outgrows the grain.
|
|
119
|
+
*/
|
|
120
|
+
granularity?: AnalyticsGranularity;
|
|
121
|
+
/** IANA zone for calendar grains (day/week/month boundaries). Default UTC. */
|
|
122
|
+
timezone?: string;
|
|
123
|
+
filters?: AnalyticsFilter[];
|
|
124
|
+
dateRange?: AnalyticsDateRange;
|
|
125
|
+
/**
|
|
126
|
+
* Grouped queries only: one `['pageviews' | 'events' | 'visits', 'asc' |
|
|
127
|
+
* 'desc']`, by a metric the query's shape carries.
|
|
128
|
+
*/
|
|
129
|
+
orderBy?: ['pageviews' | 'events' | 'visits', 'asc' | 'desc'][];
|
|
130
|
+
/** Grouped queries only. Default 25, max 1000. */
|
|
131
|
+
limit?: number;
|
|
132
|
+
offset?: number;
|
|
133
|
+
/** Scope to one release (rarely needed — analytics is app-wide). */
|
|
134
|
+
releaseId?: string;
|
|
135
|
+
}
|
|
136
|
+
export interface AnalyticsQueryResultRow {
|
|
137
|
+
/** Group keys: the entity dimension and/or `time` (bucket-start ISO). */
|
|
138
|
+
dimensions: Record<string, string>;
|
|
139
|
+
/**
|
|
140
|
+
* Only the requested-and-available metrics appear. An average with nothing
|
|
141
|
+
* to average is `null`.
|
|
142
|
+
*/
|
|
143
|
+
metrics: Partial<Record<AnalyticsCountMetric, number>> & Partial<Record<AnalyticsAverageMetric, number | null>>;
|
|
144
|
+
}
|
|
145
|
+
export interface AnalyticsQueryResponse {
|
|
146
|
+
results: AnalyticsQueryResultRow[];
|
|
147
|
+
meta: {
|
|
148
|
+
/** Which store answered: 'rollup' = lifetime, 'events' = 90-day raw. */
|
|
149
|
+
source: 'rollup' | 'events';
|
|
150
|
+
window: {
|
|
151
|
+
requested: [string, string];
|
|
152
|
+
served: [string, string];
|
|
153
|
+
};
|
|
154
|
+
/**
|
|
155
|
+
* True when an events-path window was cut: to the retention horizon, or
|
|
156
|
+
* for a query about visits, to when the app's visits were first recorded.
|
|
157
|
+
*/
|
|
158
|
+
clamped: boolean;
|
|
159
|
+
/** Requested metrics this query shape can't carry. */
|
|
160
|
+
metricsOmitted?: AnalyticsMetric[];
|
|
161
|
+
/** Grouped queries: unpaginated distinct-group count, for paging. */
|
|
162
|
+
total?: number;
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
/** Shared options for the special reads (same grammar as `query`). */
|
|
166
|
+
export interface AnalyticsReadOptions {
|
|
167
|
+
dateRange?: AnalyticsDateRange;
|
|
168
|
+
filters?: AnalyticsFilter[];
|
|
169
|
+
releaseId?: string;
|
|
170
|
+
limit?: number;
|
|
171
|
+
offset?: number;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* A funnel step: a page opened (`match: 'contains'` for any page whose path
|
|
175
|
+
* contains the text), or a custom event fired, optionally with property
|
|
176
|
+
* values it must carry.
|
|
177
|
+
*/
|
|
178
|
+
export type FunnelStep = {
|
|
179
|
+
page: string;
|
|
180
|
+
match?: 'is' | 'contains';
|
|
181
|
+
} | {
|
|
182
|
+
event: string;
|
|
183
|
+
props?: Record<string, string | number | boolean>;
|
|
184
|
+
};
|
|
185
|
+
/** What `funnel` and `paths` report about the window and the apps they read. */
|
|
186
|
+
export interface VisitReadMeta {
|
|
187
|
+
window: {
|
|
188
|
+
requested: [string, string];
|
|
189
|
+
served: [string, string];
|
|
190
|
+
};
|
|
191
|
+
/** True when the window was cut: to retention, or to when visits were first recorded. */
|
|
192
|
+
clamped: boolean;
|
|
193
|
+
/** The apps whose visits answered: this one, and those sharing its host (its mounts). */
|
|
194
|
+
apps: string[];
|
|
195
|
+
}
|
|
196
|
+
export interface FunnelOptions {
|
|
197
|
+
/** 2 to 8 steps, each reached after the one before it within one visit. */
|
|
198
|
+
steps: FunnelStep[];
|
|
199
|
+
/** Split by something a visit has once: a visit dimension, `visitorType`, `deviceType`, `country`, `browser` or `os`. */
|
|
200
|
+
breakdown?: AnalyticsDimension;
|
|
201
|
+
dateRange?: AnalyticsDateRange;
|
|
202
|
+
/** Pick visits: a visit is in when any of its rows matches every filter. */
|
|
203
|
+
filters?: AnalyticsFilter[];
|
|
204
|
+
releaseId?: string;
|
|
205
|
+
}
|
|
206
|
+
export interface FunnelResult {
|
|
207
|
+
steps: {
|
|
208
|
+
step: FunnelStep;
|
|
209
|
+
/** Visits that reached this step, having reached every one before it in order. */
|
|
210
|
+
visits: number;
|
|
211
|
+
/** Of those, the visits that didn't go on to the next step (0 on the last). */
|
|
212
|
+
dropOff: number;
|
|
213
|
+
}[];
|
|
214
|
+
/** With `breakdown`: each value's visits at every step, its 25 largest. */
|
|
215
|
+
breakdown?: {
|
|
216
|
+
dimension: string;
|
|
217
|
+
groups: {
|
|
218
|
+
value: string | null;
|
|
219
|
+
visits: number[];
|
|
220
|
+
}[];
|
|
221
|
+
};
|
|
222
|
+
meta: VisitReadMeta;
|
|
223
|
+
}
|
|
224
|
+
export interface PathsOptions {
|
|
225
|
+
/** A page path: where visits went after it. Without it, only `routes`. */
|
|
226
|
+
from?: string;
|
|
227
|
+
/** How many opening pages a route has, 1 to 5. Default 3. */
|
|
228
|
+
depth?: number;
|
|
229
|
+
/** Rows in each list, 1 to 100. Default 10. */
|
|
230
|
+
limit?: number;
|
|
231
|
+
dateRange?: AnalyticsDateRange;
|
|
232
|
+
/** Pick visits: a visit is in when any of its rows matches every filter. */
|
|
233
|
+
filters?: AnalyticsFilter[];
|
|
234
|
+
releaseId?: string;
|
|
235
|
+
}
|
|
236
|
+
export interface PathsResult {
|
|
237
|
+
/** Visits counted. */
|
|
238
|
+
visits: number;
|
|
239
|
+
/** With `from`: the page opened next, or `null` where the visit ended. */
|
|
240
|
+
next?: {
|
|
241
|
+
path: string | null;
|
|
242
|
+
visits: number;
|
|
243
|
+
}[];
|
|
244
|
+
/** The commonest routes: each visit's first `depth` pages, a page repeated in a row counted once. */
|
|
245
|
+
routes: {
|
|
246
|
+
paths: string[];
|
|
247
|
+
visits: number;
|
|
248
|
+
}[];
|
|
249
|
+
meta: VisitReadMeta;
|
|
250
|
+
}
|
|
251
|
+
export interface LiveNow {
|
|
252
|
+
/** Visitors on the app right now. */
|
|
253
|
+
count: number;
|
|
254
|
+
countries: {
|
|
255
|
+
country: string;
|
|
256
|
+
count: number;
|
|
257
|
+
}[];
|
|
258
|
+
/** Last hour of live-count samples, one per minute. `ts` is an ISO string. */
|
|
259
|
+
sparkline: {
|
|
260
|
+
ts: string;
|
|
261
|
+
count: number;
|
|
262
|
+
}[];
|
|
263
|
+
}
|
|
264
|
+
export interface TopSource {
|
|
265
|
+
sourceType: 'utm' | 'referrer' | 'direct';
|
|
266
|
+
sourceLabel: string;
|
|
267
|
+
visits: number;
|
|
268
|
+
uniqueVisitors: number;
|
|
269
|
+
/** ai_assistant | search | social | email | direct | other. */
|
|
270
|
+
category: string;
|
|
271
|
+
/** Vendor display name for classified hosts (e.g. "OpenAI"), else null. */
|
|
272
|
+
vendor: string | null;
|
|
273
|
+
}
|
|
274
|
+
export interface MapPoint {
|
|
275
|
+
city: string;
|
|
276
|
+
country: string;
|
|
277
|
+
latitude: number;
|
|
278
|
+
longitude: number;
|
|
279
|
+
pageviews: number;
|
|
280
|
+
uniqueVisitors: number;
|
|
281
|
+
}
|
|
282
|
+
export interface AiSourceVendor {
|
|
283
|
+
vendor: string;
|
|
284
|
+
pageviews: number;
|
|
285
|
+
uniqueVisitors: number;
|
|
286
|
+
hosts: string[];
|
|
287
|
+
}
|
|
288
|
+
export interface CrawlerOverview {
|
|
289
|
+
totalHits: number;
|
|
290
|
+
byVendor: {
|
|
291
|
+
vendor: string;
|
|
292
|
+
count: number;
|
|
293
|
+
}[];
|
|
294
|
+
topPages: {
|
|
295
|
+
path: string;
|
|
296
|
+
count: number;
|
|
297
|
+
}[];
|
|
298
|
+
}
|
|
299
|
+
export interface CrawlerBucket {
|
|
300
|
+
start: string;
|
|
301
|
+
total: number;
|
|
302
|
+
byVendor: Record<string, number>;
|
|
303
|
+
}
|
|
304
|
+
export interface CrawlerHit {
|
|
305
|
+
id: string;
|
|
306
|
+
releaseId: string;
|
|
307
|
+
path: string;
|
|
308
|
+
host: string | null;
|
|
309
|
+
botVendor: string;
|
|
310
|
+
botName: string;
|
|
311
|
+
country: string | null;
|
|
312
|
+
createdAt: string;
|
|
313
|
+
}
|
|
314
|
+
/** The `analytics` namespace object. */
|
|
315
|
+
export interface Analytics {
|
|
316
|
+
/** The general read: metrics × dimensions × filters × time. */
|
|
317
|
+
query(spec: AnalyticsQuerySpec): Promise<AnalyticsQueryResponse>;
|
|
318
|
+
/**
|
|
319
|
+
* Up to 10 queries in one round trip, results in request order — the right
|
|
320
|
+
* shape for a page composed of several reads (KPIs + timeseries + a few
|
|
321
|
+
* breakdowns), instead of a parallel burst of `query()` calls competing
|
|
322
|
+
* with each other against the per-app rate limit. Each query in the batch
|
|
323
|
+
* counts as one read against the limit. One invalid query fails the whole
|
|
324
|
+
* batch (the error names its index).
|
|
325
|
+
*/
|
|
326
|
+
batch(specs: AnalyticsQuerySpec[]): Promise<AnalyticsQueryResponse[]>;
|
|
327
|
+
/**
|
|
328
|
+
* How many visits went through the steps in order, and where they dropped
|
|
329
|
+
* off. Follows a visitor across the apps sharing this one's host. Raw
|
|
330
|
+
* events (90 days); counts as 5 reads against the limit.
|
|
331
|
+
*/
|
|
332
|
+
funnel(options: FunnelOptions): Promise<FunnelResult>;
|
|
333
|
+
/**
|
|
334
|
+
* The routes visits took: where they went after a page, and the pages they
|
|
335
|
+
* commonly opened with. Raw events (90 days); counts as 5 reads.
|
|
336
|
+
*/
|
|
337
|
+
paths(options?: PathsOptions): Promise<PathsResult>;
|
|
338
|
+
/** Who's on the app right now (Redis presence, no time window). */
|
|
339
|
+
live(): Promise<LiveNow>;
|
|
340
|
+
/**
|
|
341
|
+
* Ranked traffic sources — each session attributed to its first pageview's
|
|
342
|
+
* source (UTM > referrer > direct), classified by category/vendor. Always
|
|
343
|
+
* reads raw events (90-day window).
|
|
344
|
+
*/
|
|
345
|
+
sources(options?: AnalyticsReadOptions): Promise<{
|
|
346
|
+
results: TopSource[];
|
|
347
|
+
total: number;
|
|
348
|
+
}>;
|
|
349
|
+
/** City-level visitor points with coordinates. */
|
|
350
|
+
map(options?: AnalyticsReadOptions): Promise<{
|
|
351
|
+
points: MapPoint[];
|
|
352
|
+
total: number;
|
|
353
|
+
}>;
|
|
354
|
+
/** AI-assistant referral traffic, aggregated per vendor. */
|
|
355
|
+
aiSources(options?: Omit<AnalyticsReadOptions, 'filters' | 'offset'>): Promise<{
|
|
356
|
+
results: AiSourceVendor[];
|
|
357
|
+
hosts: {
|
|
358
|
+
host: string;
|
|
359
|
+
pageviews: number;
|
|
360
|
+
uniqueVisitors: number;
|
|
361
|
+
}[];
|
|
362
|
+
}>;
|
|
363
|
+
/** Bot / AI-crawler ingestion of the app's pages. */
|
|
364
|
+
crawlers: {
|
|
365
|
+
overview(options?: Omit<AnalyticsReadOptions, 'filters' | 'limit' | 'offset'> & {
|
|
366
|
+
topPagesLimit?: number;
|
|
367
|
+
}): Promise<CrawlerOverview>;
|
|
368
|
+
timeseries(options?: Omit<AnalyticsReadOptions, 'filters' | 'limit' | 'offset'> & {
|
|
369
|
+
buckets?: number;
|
|
370
|
+
}): Promise<{
|
|
371
|
+
buckets: CrawlerBucket[];
|
|
372
|
+
}>;
|
|
373
|
+
recent(options?: Pick<AnalyticsReadOptions, 'dateRange' | 'releaseId' | 'limit'>): Promise<{
|
|
374
|
+
results: CrawlerHit[];
|
|
375
|
+
}>;
|
|
376
|
+
};
|
|
377
|
+
}
|
|
378
|
+
/**
|
|
379
|
+
* Create an Analytics namespace bound to a transport.
|
|
380
|
+
*
|
|
381
|
+
* @internal Called by MindStudioAgent; not part of the public API — access
|
|
382
|
+
* `analytics` via the agent instance or the top-level export.
|
|
383
|
+
*/
|
|
384
|
+
export declare function createAnalytics(call: AnalyticsTransport): Analytics;
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Auth namespace — role-based access control for MindStudio apps.
|
|
3
|
+
*
|
|
4
|
+
* Provides synchronous access to the current user's identity and roles
|
|
5
|
+
* within an app. Hydrated once from app context (either sandbox globals
|
|
6
|
+
* or the `GET /helpers/app-context` endpoint), then all access is sync.
|
|
7
|
+
*
|
|
8
|
+
* ## How it works
|
|
9
|
+
*
|
|
10
|
+
* 1. The platform stores role assignments per app: `{ userId, roleName }[]`
|
|
11
|
+
* 2. On context hydration, the full role map is loaded into memory
|
|
12
|
+
* 3. `auth.hasRole()` / `auth.requireRole()` are simple array lookups
|
|
13
|
+
* 4. `auth.getUsersByRole()` scans the preloaded assignments
|
|
14
|
+
*
|
|
15
|
+
* ## Usage
|
|
16
|
+
*
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { auth, Roles } from '@mindstudio-ai/agent';
|
|
19
|
+
*
|
|
20
|
+
* // Check permissions
|
|
21
|
+
* if (auth.hasRole(Roles.admin, Roles.approver)) {
|
|
22
|
+
* // user has at least one of these roles
|
|
23
|
+
* }
|
|
24
|
+
*
|
|
25
|
+
* // Gate a route — throws 403 if user lacks the role
|
|
26
|
+
* auth.requireRole(Roles.admin);
|
|
27
|
+
*
|
|
28
|
+
* // Look up who has a role
|
|
29
|
+
* const admins = auth.getUsersByRole(Roles.admin);
|
|
30
|
+
* ```
|
|
31
|
+
*
|
|
32
|
+
* ## Roles proxy
|
|
33
|
+
*
|
|
34
|
+
* `Roles` is a convenience proxy: `Roles.admin` === `"admin"`. It provides
|
|
35
|
+
* discoverability and typo prevention. In the future, the compilation
|
|
36
|
+
* pipeline will generate a typed `Roles` object from `app.json`, giving
|
|
37
|
+
* compile-time safety. For now, any string property access works.
|
|
38
|
+
*/
|
|
39
|
+
import type { AppAuthContext } from '../types.js';
|
|
40
|
+
/**
|
|
41
|
+
* Auth context for the current execution. Created from the app's role
|
|
42
|
+
* assignments and the current user's identity.
|
|
43
|
+
*
|
|
44
|
+
* All methods are synchronous — the full role map is preloaded at
|
|
45
|
+
* context hydration time.
|
|
46
|
+
*/
|
|
47
|
+
export declare class AuthContext {
|
|
48
|
+
/** The current user's ID, or null for unauthenticated users. */
|
|
49
|
+
readonly userId: string | null;
|
|
50
|
+
/** The current user's roles in this app. */
|
|
51
|
+
readonly roles: readonly string[];
|
|
52
|
+
/** All role assignments for this app (all users, all roles). */
|
|
53
|
+
private readonly _roleAssignments;
|
|
54
|
+
constructor(ctx: AppAuthContext);
|
|
55
|
+
/**
|
|
56
|
+
* Check if the current user has **any** of the given roles.
|
|
57
|
+
* Returns true if at least one matches.
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* ```ts
|
|
61
|
+
* if (auth.hasRole(Roles.admin, Roles.approver)) {
|
|
62
|
+
* // user is an admin OR an approver
|
|
63
|
+
* }
|
|
64
|
+
* ```
|
|
65
|
+
*/
|
|
66
|
+
hasRole(...roles: string[]): boolean;
|
|
67
|
+
/**
|
|
68
|
+
* Require the current user to have at least one of the given roles.
|
|
69
|
+
* Throws a `MindStudioError` with code `'forbidden'` and status 403
|
|
70
|
+
* if the user lacks all of the specified roles.
|
|
71
|
+
*
|
|
72
|
+
* Use this at the top of route handlers to gate access.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* auth.requireRole(Roles.admin);
|
|
77
|
+
* // code below only runs if user is an admin
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
80
|
+
requireRole(...roles: string[]): void;
|
|
81
|
+
/**
|
|
82
|
+
* Get all user IDs that have the given role in this app.
|
|
83
|
+
* Synchronous — scans the preloaded role assignments.
|
|
84
|
+
*
|
|
85
|
+
* @example
|
|
86
|
+
* ```ts
|
|
87
|
+
* const reviewers = auth.getUsersByRole(Roles.reviewer);
|
|
88
|
+
* // ['user-id-1', 'user-id-2', ...]
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
91
|
+
getUsersByRole(role: string): string[];
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Convenience proxy for referencing role names. Any property access
|
|
95
|
+
* returns the property name as a string: `Roles.admin === "admin"`.
|
|
96
|
+
*
|
|
97
|
+
* This provides:
|
|
98
|
+
* - Discoverability via autocomplete (in typed environments)
|
|
99
|
+
* - Typo prevention (vs raw string literals)
|
|
100
|
+
* - Forward compatibility with the future typed Roles generation
|
|
101
|
+
*
|
|
102
|
+
* In the future, the compilation pipeline will generate a typed `Roles`
|
|
103
|
+
* object from `app.json` roles, replacing this proxy with compile-time
|
|
104
|
+
* checked constants.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```ts
|
|
108
|
+
* Roles.admin // "admin"
|
|
109
|
+
* Roles.approver // "approver"
|
|
110
|
+
* Roles.anything // "anything" (no runtime error, any string works)
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
export declare const Roles: Record<string, string>;
|