@mindstudio-ai/agent 0.1.176 → 0.1.177

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.
Files changed (49) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/dist/analytics/index.d.ts +384 -0
  3. package/dist/auth/index.d.ts +113 -0
  4. package/dist/browser/index.d.ts +332 -0
  5. package/dist/cli.js +27 -27
  6. package/dist/client.d.ts +767 -0
  7. package/dist/config.d.ts +13 -0
  8. package/dist/context.d.ts +125 -0
  9. package/dist/datasources/index.d.ts +52 -0
  10. package/dist/datasources/source.d.ts +1074 -0
  11. package/dist/db/aggregate.d.ts +101 -0
  12. package/dist/db/index.d.ts +280 -0
  13. package/dist/db/mutation.d.ts +65 -0
  14. package/dist/db/predicate.d.ts +85 -0
  15. package/dist/db/query.d.ts +233 -0
  16. package/dist/db/raw.d.ts +36 -0
  17. package/dist/db/readBatching.d.ts +36 -0
  18. package/dist/db/scanHints.d.ts +8 -0
  19. package/dist/db/sql.d.ts +136 -0
  20. package/dist/db/table.d.ts +146 -0
  21. package/dist/db/time.d.ts +17 -0
  22. package/dist/db/types.d.ts +237 -0
  23. package/dist/db-ws.d.ts +35 -0
  24. package/dist/email/index.d.ts +396 -0
  25. package/dist/errors.d.ts +34 -0
  26. package/dist/events/index.d.ts +127 -0
  27. package/dist/files/index.d.ts +62 -0
  28. package/dist/files/store.d.ts +244 -0
  29. package/dist/generated/metadata.d.ts +8 -0
  30. package/dist/generated/snippets.d.ts +8 -0
  31. package/dist/generated/steps.d.ts +2745 -0
  32. package/dist/generated/types.d.ts +4234 -0
  33. package/dist/http.d.ts +22 -0
  34. package/dist/index.d.ts +59 -13329
  35. package/dist/index.js +15 -15
  36. package/dist/index.js.map +7 -1
  37. package/dist/jewel/index.d.ts +325 -0
  38. package/dist/mapper/index.d.ts +229 -0
  39. package/dist/rate-limit.d.ts +25 -0
  40. package/dist/reader/index.d.ts +170 -0
  41. package/dist/respond.d.ts +68 -0
  42. package/dist/task/index.d.ts +18 -0
  43. package/dist/task/local.d.ts +48 -0
  44. package/dist/task/schema.d.ts +120 -0
  45. package/dist/task/types.d.ts +203 -0
  46. package/dist/types.d.ts +591 -0
  47. package/dist/voice/index.d.ts +87 -0
  48. package/package.json +6 -12
  49. package/dist/postinstall.js +0 -12115
package/CHANGELOG.md CHANGED
@@ -4,6 +4,13 @@ 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.177
8
+
9
+ ### Changed behavior
10
+
11
+ - 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.
12
+ - 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.
13
+
7
14
  ## 0.1.176
8
15
 
9
16
  ### 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>;