react-semaphor 0.1.574 → 0.1.575

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.
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { QueryTrigger } from './catalog.js';
2
+ import { QueryTrigger } from './vocabulary.js';
3
3
  /**
4
4
  * What the browser adds to a query body to say where a query came from
5
5
  * (usage-events TECH-SPEC §2.1, M7). A label, never input: a missing,
@@ -1,15 +1,40 @@
1
+ import { z } from 'zod';
2
+ import { DashboardOpenedDetails, QueryExecutedDetails, TokenIssuedDetails, ToolCalledDetails } from './details.js';
1
3
  /**
2
- * The usage events catalog (usage-events TECH-SPEC §2.1). Phase Q holds only
3
- * the query vocabulary, which query tags and the query routes need before any
4
- * event exists; the event types, envelope and schemas land with their
5
- * producers (Phases 1, 2 and 6).
4
+ * The usage events catalog (usage-events TECH-SPEC §2.1): every event type,
5
+ * its category, version, producer and details schema, and the vocabulary the
6
+ * envelope and query tags share. A type lands with its producer: Phase 1 adds
7
+ * `token_issued`, Phase 2 the server events; Phase 6 adds its own.
6
8
  */
7
- /** What a query run was for, derived on the server from its own inputs. */
8
- export declare const QUERY_KINDS: readonly ["card", "matrix_window", "filter_options", "control_options", "sql", "export"];
9
- export type QueryKind = (typeof QUERY_KINDS)[number];
10
- /** One data-service call inside a query run. */
11
- export declare const QUERY_STATEMENTS: readonly ["main", "row_count", "totals"];
12
- export type QueryStatement = (typeof QUERY_STATEMENTS)[number];
13
- /** The gesture the browser says a query followed (Phase 3 sends it). */
14
- export declare const QUERY_TRIGGERS: readonly ["initial_load", "input_change", "click_filter", "drill", "page", "sort", "refresh"];
15
- export type QueryTrigger = (typeof QUERY_TRIGGERS)[number];
9
+ export declare const USAGE_EVENT_TYPES: readonly ["token_issued", "dashboard_opened", "query_executed", "tool_called"];
10
+ export type UsageEventType = (typeof USAGE_EVENT_TYPES)[number];
11
+ export declare const USAGE_EVENT_CATEGORIES: readonly ["usage", "runtime", "agent", "delivery"];
12
+ export type UsageEventCategory = (typeof USAGE_EVENT_CATEGORIES)[number];
13
+ export declare const USAGE_ACTOR_TYPES: readonly ["org_user", "tenant_user", "tenant", "api_key", "system", "anonymous"];
14
+ export type UsageActorType = (typeof USAGE_ACTOR_TYPES)[number];
15
+ export declare const USAGE_SURFACES: readonly ["console", "embed", "public_link", "mcp", "api", "scheduler", "pdf_renderer"];
16
+ export type UsageSurface = (typeof USAGE_SURFACES)[number];
17
+ export declare const USAGE_OUTCOMES: readonly ["succeeded", "failed", "cancelled", "timed_out"];
18
+ export type UsageOutcome = (typeof USAGE_OUTCOMES)[number];
19
+ export declare const USAGE_PRODUCERS: readonly ["app", "scheduler"];
20
+ export type UsageProducer = (typeof USAGE_PRODUCERS)[number];
21
+ export type UsageEventDetailsByType = {
22
+ token_issued: TokenIssuedDetails;
23
+ dashboard_opened: DashboardOpenedDetails;
24
+ query_executed: QueryExecutedDetails;
25
+ tool_called: ToolCalledDetails;
26
+ };
27
+ export type UsageEventCatalogEntry<T extends UsageEventType> = {
28
+ category: UsageEventCategory;
29
+ /** 1 for every event until a breaking change bumps it (AL-D29). */
30
+ version: number;
31
+ /** Repo-relative path of the one producer module (AL-INV-6). */
32
+ emittedBy: string;
33
+ /** Carries personal data or free text the user sent (AL-INV-5). */
34
+ personalData: boolean;
35
+ detailsSchema: z.ZodType<UsageEventDetailsByType[T]>;
36
+ };
37
+ export declare const USAGE_EVENT_CATALOG: {
38
+ [T in UsageEventType]: UsageEventCatalogEntry<T>;
39
+ };
40
+ export * from './vocabulary.js';
@@ -0,0 +1,243 @@
1
+ import { z } from 'zod';
2
+ export declare const tokenIssuedDetailsSchema: z.ZodObject<{
3
+ token_type: z.ZodEnum<["dashboard", "project"]>;
4
+ token_purpose: z.ZodOptional<z.ZodEnum<["embed", "console"]>>;
5
+ ttl_s: z.ZodOptional<z.ZodNumber>;
6
+ embed_origin: z.ZodOptional<z.ZodString>;
7
+ initial_dashboard_id: z.ZodOptional<z.ZodString>;
8
+ dashboard_title: z.ZodOptional<z.ZodString>;
9
+ project_name: z.ZodOptional<z.ZodString>;
10
+ user_verified: z.ZodBoolean;
11
+ user_email: z.ZodOptional<z.ZodString>;
12
+ user_display_name: z.ZodOptional<z.ZodString>;
13
+ tenant_name: z.ZodOptional<z.ZodString>;
14
+ role: z.ZodOptional<z.ZodString>;
15
+ user_provisioned: z.ZodOptional<z.ZodBoolean>;
16
+ domain_access_mode: z.ZodOptional<z.ZodEnum<["all", "none", "include", "exclude"]>>;
17
+ domain_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
18
+ rls_policy_names: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
19
+ cls_policy_names: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
20
+ has_sls: z.ZodOptional<z.ZodBoolean>;
21
+ security_param_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
22
+ timezone: z.ZodOptional<z.ZodString>;
23
+ mcp_scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
24
+ mcp_sql: z.ZodOptional<z.ZodBoolean>;
25
+ mcp_live: z.ZodOptional<z.ZodBoolean>;
26
+ }, "strict", z.ZodTypeAny, {
27
+ token_type: "dashboard" | "project";
28
+ user_verified: boolean;
29
+ timezone?: string | undefined;
30
+ role?: string | undefined;
31
+ token_purpose?: "embed" | "console" | undefined;
32
+ ttl_s?: number | undefined;
33
+ embed_origin?: string | undefined;
34
+ initial_dashboard_id?: string | undefined;
35
+ dashboard_title?: string | undefined;
36
+ project_name?: string | undefined;
37
+ user_email?: string | undefined;
38
+ user_display_name?: string | undefined;
39
+ tenant_name?: string | undefined;
40
+ user_provisioned?: boolean | undefined;
41
+ domain_access_mode?: "none" | "all" | "include" | "exclude" | undefined;
42
+ domain_ids?: string[] | undefined;
43
+ rls_policy_names?: string[] | undefined;
44
+ cls_policy_names?: string[] | undefined;
45
+ has_sls?: boolean | undefined;
46
+ security_param_keys?: string[] | undefined;
47
+ mcp_scopes?: string[] | undefined;
48
+ mcp_sql?: boolean | undefined;
49
+ mcp_live?: boolean | undefined;
50
+ }, {
51
+ token_type: "dashboard" | "project";
52
+ user_verified: boolean;
53
+ timezone?: string | undefined;
54
+ role?: string | undefined;
55
+ token_purpose?: "embed" | "console" | undefined;
56
+ ttl_s?: number | undefined;
57
+ embed_origin?: string | undefined;
58
+ initial_dashboard_id?: string | undefined;
59
+ dashboard_title?: string | undefined;
60
+ project_name?: string | undefined;
61
+ user_email?: string | undefined;
62
+ user_display_name?: string | undefined;
63
+ tenant_name?: string | undefined;
64
+ user_provisioned?: boolean | undefined;
65
+ domain_access_mode?: "none" | "all" | "include" | "exclude" | undefined;
66
+ domain_ids?: string[] | undefined;
67
+ rls_policy_names?: string[] | undefined;
68
+ cls_policy_names?: string[] | undefined;
69
+ has_sls?: boolean | undefined;
70
+ security_param_keys?: string[] | undefined;
71
+ mcp_scopes?: string[] | undefined;
72
+ mcp_sql?: boolean | undefined;
73
+ mcp_live?: boolean | undefined;
74
+ }>;
75
+ export type TokenIssuedDetails = z.infer<typeof tokenIssuedDetailsSchema>;
76
+ export declare const dashboardOpenedDetailsSchema: z.ZodObject<{
77
+ requested_version: z.ZodOptional<z.ZodNumber>;
78
+ served: z.ZodOptional<z.ZodEnum<["current", "version"]>>;
79
+ dashboard_title: z.ZodOptional<z.ZodString>;
80
+ project_name: z.ZodOptional<z.ZodString>;
81
+ sheet_count: z.ZodOptional<z.ZodNumber>;
82
+ card_count: z.ZodOptional<z.ZodNumber>;
83
+ }, "strict", z.ZodTypeAny, {
84
+ dashboard_title?: string | undefined;
85
+ project_name?: string | undefined;
86
+ requested_version?: number | undefined;
87
+ served?: "version" | "current" | undefined;
88
+ sheet_count?: number | undefined;
89
+ card_count?: number | undefined;
90
+ }, {
91
+ dashboard_title?: string | undefined;
92
+ project_name?: string | undefined;
93
+ requested_version?: number | undefined;
94
+ served?: "version" | "current" | undefined;
95
+ sheet_count?: number | undefined;
96
+ card_count?: number | undefined;
97
+ }>;
98
+ export type DashboardOpenedDetails = z.infer<typeof dashboardOpenedDetailsSchema>;
99
+ /** One data-service call inside a query run. */
100
+ export declare const queryStatementRecordSchema: z.ZodObject<{
101
+ statement: z.ZodEnum<["main", "row_count", "totals"]>;
102
+ duration_ms: z.ZodNumber;
103
+ outcome: z.ZodEnum<["succeeded", "failed", "cancelled"]>;
104
+ rows: z.ZodOptional<z.ZodNumber>;
105
+ }, "strict", z.ZodTypeAny, {
106
+ outcome: "cancelled" | "failed" | "succeeded";
107
+ statement: "totals" | "main" | "row_count";
108
+ duration_ms: number;
109
+ rows?: number | undefined;
110
+ }, {
111
+ outcome: "cancelled" | "failed" | "succeeded";
112
+ statement: "totals" | "main" | "row_count";
113
+ duration_ms: number;
114
+ rows?: number | undefined;
115
+ }>;
116
+ export declare const queryExecutedDetailsSchema: z.ZodObject<{
117
+ data_service_calls: z.ZodNumber;
118
+ query_run_id: z.ZodString;
119
+ parent_query_run_id: z.ZodOptional<z.ZodString>;
120
+ query_kind: z.ZodOptional<z.ZodEnum<["card", "matrix_window", "filter_options", "control_options", "sql", "export"]>>;
121
+ statements: z.ZodArray<z.ZodObject<{
122
+ statement: z.ZodEnum<["main", "row_count", "totals"]>;
123
+ duration_ms: z.ZodNumber;
124
+ outcome: z.ZodEnum<["succeeded", "failed", "cancelled"]>;
125
+ rows: z.ZodOptional<z.ZodNumber>;
126
+ }, "strict", z.ZodTypeAny, {
127
+ outcome: "cancelled" | "failed" | "succeeded";
128
+ statement: "totals" | "main" | "row_count";
129
+ duration_ms: number;
130
+ rows?: number | undefined;
131
+ }, {
132
+ outcome: "cancelled" | "failed" | "succeeded";
133
+ statement: "totals" | "main" | "row_count";
134
+ duration_ms: number;
135
+ rows?: number | undefined;
136
+ }>, "many">;
137
+ trigger: z.ZodOptional<z.ZodEnum<["initial_load", "input_change", "click_filter", "drill", "page", "sort", "refresh"]>>;
138
+ card_title: z.ZodOptional<z.ZodString>;
139
+ card_type: z.ZodOptional<z.ZodString>;
140
+ project_name: z.ZodOptional<z.ZodString>;
141
+ connection_name: z.ZodOptional<z.ZodString>;
142
+ connection_type: z.ZodOptional<z.ZodString>;
143
+ dialect: z.ZodOptional<z.ZodString>;
144
+ dataset: z.ZodOptional<z.ZodString>;
145
+ rows: z.ZodOptional<z.ZodNumber>;
146
+ row_limit_exceeded: z.ZodOptional<z.ZodBoolean>;
147
+ sql_text: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
148
+ sql_truncated: z.ZodOptional<z.ZodBoolean>;
149
+ sql_hash: z.ZodOptional<z.ZodString>;
150
+ input_ids_applied: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
151
+ page: z.ZodOptional<z.ZodNumber>;
152
+ export_job_id: z.ZodOptional<z.ZodString>;
153
+ }, "strict", z.ZodTypeAny, {
154
+ data_service_calls: number;
155
+ query_run_id: string;
156
+ statements: {
157
+ outcome: "cancelled" | "failed" | "succeeded";
158
+ statement: "totals" | "main" | "row_count";
159
+ duration_ms: number;
160
+ rows?: number | undefined;
161
+ }[];
162
+ dialect?: string | undefined;
163
+ page?: number | undefined;
164
+ rows?: number | undefined;
165
+ dataset?: string | undefined;
166
+ trigger?: "sort" | "page" | "refresh" | "drill" | "initial_load" | "input_change" | "click_filter" | undefined;
167
+ project_name?: string | undefined;
168
+ parent_query_run_id?: string | undefined;
169
+ query_kind?: "card" | "sql" | "export" | "matrix_window" | "filter_options" | "control_options" | undefined;
170
+ card_title?: string | undefined;
171
+ card_type?: string | undefined;
172
+ connection_name?: string | undefined;
173
+ connection_type?: string | undefined;
174
+ row_limit_exceeded?: boolean | undefined;
175
+ sql_text?: string | undefined;
176
+ sql_truncated?: boolean | undefined;
177
+ sql_hash?: string | undefined;
178
+ input_ids_applied?: string[] | undefined;
179
+ export_job_id?: string | undefined;
180
+ }, {
181
+ data_service_calls: number;
182
+ query_run_id: string;
183
+ statements: {
184
+ outcome: "cancelled" | "failed" | "succeeded";
185
+ statement: "totals" | "main" | "row_count";
186
+ duration_ms: number;
187
+ rows?: number | undefined;
188
+ }[];
189
+ dialect?: string | undefined;
190
+ page?: number | undefined;
191
+ rows?: number | undefined;
192
+ dataset?: string | undefined;
193
+ trigger?: "sort" | "page" | "refresh" | "drill" | "initial_load" | "input_change" | "click_filter" | undefined;
194
+ project_name?: string | undefined;
195
+ parent_query_run_id?: string | undefined;
196
+ query_kind?: "card" | "sql" | "export" | "matrix_window" | "filter_options" | "control_options" | undefined;
197
+ card_title?: string | undefined;
198
+ card_type?: string | undefined;
199
+ connection_name?: string | undefined;
200
+ connection_type?: string | undefined;
201
+ row_limit_exceeded?: boolean | undefined;
202
+ sql_text?: string | undefined;
203
+ sql_truncated?: boolean | undefined;
204
+ sql_hash?: string | undefined;
205
+ input_ids_applied?: string[] | undefined;
206
+ export_job_id?: string | undefined;
207
+ }>;
208
+ export type QueryExecutedDetails = z.infer<typeof queryExecutedDetailsSchema>;
209
+ export declare const toolCalledDetailsSchema: z.ZodObject<{
210
+ tool: z.ZodString;
211
+ args_json: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
212
+ args_truncated: z.ZodOptional<z.ZodBoolean>;
213
+ arg_keys: z.ZodArray<z.ZodString, "many">;
214
+ user_agent: z.ZodOptional<z.ZodString>;
215
+ oauth_client: z.ZodOptional<z.ZodString>;
216
+ credential: z.ZodOptional<z.ZodString>;
217
+ access_mode: z.ZodOptional<z.ZodString>;
218
+ scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
219
+ response_bytes: z.ZodOptional<z.ZodNumber>;
220
+ }, "strict", z.ZodTypeAny, {
221
+ tool: string;
222
+ arg_keys: string[];
223
+ args_json?: string | undefined;
224
+ args_truncated?: boolean | undefined;
225
+ user_agent?: string | undefined;
226
+ oauth_client?: string | undefined;
227
+ credential?: string | undefined;
228
+ access_mode?: string | undefined;
229
+ scopes?: string[] | undefined;
230
+ response_bytes?: number | undefined;
231
+ }, {
232
+ tool: string;
233
+ arg_keys: string[];
234
+ args_json?: string | undefined;
235
+ args_truncated?: boolean | undefined;
236
+ user_agent?: string | undefined;
237
+ oauth_client?: string | undefined;
238
+ credential?: string | undefined;
239
+ access_mode?: string | undefined;
240
+ scopes?: string[] | undefined;
241
+ response_bytes?: number | undefined;
242
+ }>;
243
+ export type ToolCalledDetails = z.infer<typeof toolCalledDetailsSchema>;
@@ -0,0 +1,146 @@
1
+ import { z } from 'zod';
2
+ import { UsageActorType, UsageEventCategory, UsageEventDetailsByType, UsageEventType, UsageOutcome, UsageProducer, UsageSurface } from './catalog.js';
3
+ /**
4
+ * Every event has exactly these keys, nullable where marked (usage-events
5
+ * TECH-SPEC §2.1). Customer-facing keys are snake_case.
6
+ */
7
+ export type UsageEventEnvelope = {
8
+ /** UUIDv7, minted by emitUsageEvent; the dedupe key. */
9
+ event_id: string;
10
+ event_type: UsageEventType;
11
+ /** The catalog entry's version. */
12
+ event_version: number;
13
+ /** The catalog entry's category. */
14
+ category: UsageEventCategory;
15
+ /** ISO 8601 UTC, producer clock. */
16
+ occurred_at: string;
17
+ producer: UsageProducer;
18
+ /** The producer's package version. */
19
+ release: string;
20
+ /** Null only when no org is known (a refused token request). */
21
+ org_id: string | null;
22
+ project_id: string | null;
23
+ tenant_id: string | null;
24
+ actor_type: UsageActorType;
25
+ org_user_id: string | null;
26
+ /** The token's endUserId, as the token carries it. */
27
+ tenant_user_id: string | null;
28
+ surface: UsageSurface;
29
+ /** The token's `sid` claim. */
30
+ session_id: string | null;
31
+ operation_id: string | null;
32
+ dashboard_id: string | null;
33
+ sheet_id: string | null;
34
+ card_id: string | null;
35
+ connection_id: string | null;
36
+ domain_id: string | null;
37
+ outcome: UsageOutcome | null;
38
+ duration_ms: number | null;
39
+ /** Set exactly when outcome is 'failed' or 'timed_out'. */
40
+ error: {
41
+ code: string;
42
+ message: string;
43
+ } | null;
44
+ };
45
+ export type UsageEvent<T extends UsageEventType = UsageEventType> = {
46
+ [K in T]: UsageEventEnvelope & {
47
+ event_type: K;
48
+ details: UsageEventDetailsByType[K];
49
+ };
50
+ }[T];
51
+ /** The longest `error.message`, in UTF-8 bytes; producers cut to it. */
52
+ export declare const USAGE_EVENT_TEXT_MAX_BYTES: number;
53
+ export declare const usageEventEnvelopeSchema: z.ZodObject<{
54
+ event_id: z.ZodString;
55
+ event_type: z.ZodEnum<["token_issued", "dashboard_opened", "query_executed", "tool_called"]>;
56
+ event_version: z.ZodNumber;
57
+ category: z.ZodEnum<["usage", "runtime", "agent", "delivery"]>;
58
+ occurred_at: z.ZodString;
59
+ producer: z.ZodEnum<["app", "scheduler"]>;
60
+ release: z.ZodString;
61
+ org_id: z.ZodNullable<z.ZodString>;
62
+ project_id: z.ZodNullable<z.ZodString>;
63
+ tenant_id: z.ZodNullable<z.ZodString>;
64
+ actor_type: z.ZodEnum<["org_user", "tenant_user", "tenant", "api_key", "system", "anonymous"]>;
65
+ org_user_id: z.ZodNullable<z.ZodString>;
66
+ tenant_user_id: z.ZodNullable<z.ZodString>;
67
+ surface: z.ZodEnum<["console", "embed", "public_link", "mcp", "api", "scheduler", "pdf_renderer"]>;
68
+ session_id: z.ZodNullable<z.ZodString>;
69
+ operation_id: z.ZodNullable<z.ZodString>;
70
+ dashboard_id: z.ZodNullable<z.ZodString>;
71
+ sheet_id: z.ZodNullable<z.ZodString>;
72
+ card_id: z.ZodNullable<z.ZodString>;
73
+ connection_id: z.ZodNullable<z.ZodString>;
74
+ domain_id: z.ZodNullable<z.ZodString>;
75
+ outcome: z.ZodNullable<z.ZodEnum<["succeeded", "failed", "cancelled", "timed_out"]>>;
76
+ duration_ms: z.ZodNullable<z.ZodNumber>;
77
+ error: z.ZodNullable<z.ZodObject<{
78
+ code: z.ZodString;
79
+ message: z.ZodEffects<z.ZodString, string, string>;
80
+ }, "strict", z.ZodTypeAny, {
81
+ code: string;
82
+ message: string;
83
+ }, {
84
+ code: string;
85
+ message: string;
86
+ }>>;
87
+ details: z.ZodUnknown;
88
+ }, "strict", z.ZodTypeAny, {
89
+ error: {
90
+ code: string;
91
+ message: string;
92
+ } | null;
93
+ surface: "api" | "embed" | "console" | "public_link" | "mcp" | "scheduler" | "pdf_renderer";
94
+ category: "usage" | "runtime" | "delivery" | "agent";
95
+ connection_id: string | null;
96
+ card_id: string | null;
97
+ sheet_id: string | null;
98
+ outcome: "cancelled" | "failed" | "timed_out" | "succeeded" | null;
99
+ domain_id: string | null;
100
+ project_id: string | null;
101
+ dashboard_id: string | null;
102
+ duration_ms: number | null;
103
+ event_id: string;
104
+ event_type: "token_issued" | "dashboard_opened" | "query_executed" | "tool_called";
105
+ event_version: number;
106
+ occurred_at: string;
107
+ producer: "scheduler" | "app";
108
+ release: string;
109
+ org_id: string | null;
110
+ tenant_id: string | null;
111
+ actor_type: "system" | "tenant" | "tenant_user" | "org_user" | "anonymous" | "api_key";
112
+ org_user_id: string | null;
113
+ tenant_user_id: string | null;
114
+ session_id: string | null;
115
+ operation_id: string | null;
116
+ details?: unknown;
117
+ }, {
118
+ error: {
119
+ code: string;
120
+ message: string;
121
+ } | null;
122
+ surface: "api" | "embed" | "console" | "public_link" | "mcp" | "scheduler" | "pdf_renderer";
123
+ category: "usage" | "runtime" | "delivery" | "agent";
124
+ connection_id: string | null;
125
+ card_id: string | null;
126
+ sheet_id: string | null;
127
+ outcome: "cancelled" | "failed" | "timed_out" | "succeeded" | null;
128
+ domain_id: string | null;
129
+ project_id: string | null;
130
+ dashboard_id: string | null;
131
+ duration_ms: number | null;
132
+ event_id: string;
133
+ event_type: "token_issued" | "dashboard_opened" | "query_executed" | "tool_called";
134
+ event_version: number;
135
+ occurred_at: string;
136
+ producer: "scheduler" | "app";
137
+ release: string;
138
+ org_id: string | null;
139
+ tenant_id: string | null;
140
+ actor_type: "system" | "tenant" | "tenant_user" | "org_user" | "anonymous" | "api_key";
141
+ org_user_id: string | null;
142
+ tenant_user_id: string | null;
143
+ session_id: string | null;
144
+ operation_id: string | null;
145
+ details?: unknown;
146
+ }>;
@@ -4,3 +4,6 @@
4
4
  */
5
5
  export * from './catalog.js';
6
6
  export * from './attribution.js';
7
+ export * from './details.js';
8
+ export * from './envelope.js';
9
+ export * from './validate.js';
@@ -0,0 +1,12 @@
1
+ import { UsageEvent } from './envelope.js';
2
+ /**
3
+ * Every event passes this before it leaves its producer (AL-INV-3). Issues
4
+ * name the path and the rule broken, never a value, so they can be logged.
5
+ */
6
+ export declare function parseUsageEvent(value: unknown): {
7
+ ok: true;
8
+ event: UsageEvent;
9
+ } | {
10
+ ok: false;
11
+ issues: string[];
12
+ };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The query vocabulary (usage-events TECH-SPEC 2.1), shared by the query
3
+ * tags (Phase Q), the attribution schema and `query_executed` (Phase 2). Its
4
+ * own module so `details.ts` can use it without importing the catalog.
5
+ */
6
+ /** What a query run was for, derived on the server from its own inputs. */
7
+ export declare const QUERY_KINDS: readonly ["card", "matrix_window", "filter_options", "control_options", "sql", "export"];
8
+ export type QueryKind = (typeof QUERY_KINDS)[number];
9
+ /** One data-service call inside a query run. */
10
+ export declare const QUERY_STATEMENTS: readonly ["main", "row_count", "totals"];
11
+ export type QueryStatement = (typeof QUERY_STATEMENTS)[number];
12
+ /** The gesture the browser says a query followed (Phase 3 sends it). */
13
+ export declare const QUERY_TRIGGERS: readonly ["initial_load", "input_change", "click_filter", "drill", "page", "sort", "refresh"];
14
+ export type QueryTrigger = (typeof QUERY_TRIGGERS)[number];
@@ -1,12 +1,12 @@
1
- import { z as t } from "zod";
2
- const r = [
1
+ import { z as e } from "zod";
2
+ const f = [
3
3
  "card",
4
4
  "matrix_window",
5
5
  "filter_options",
6
6
  "control_options",
7
7
  "sql",
8
8
  "export"
9
- ], s = ["main", "row_count", "totals"], n = [
9
+ ], x = ["main", "row_count", "totals"], b = [
10
10
  "initial_load",
11
11
  "input_change",
12
12
  "click_filter",
@@ -14,19 +14,196 @@ const r = [
14
14
  "page",
15
15
  "sort",
16
16
  "refresh"
17
- ], a = 128, c = 500, o = t.string().max(a).optional().catch(void 0), i = t.string().max(c).optional().catch(void 0), l = t.object({
18
- operationId: o,
19
- trigger: t.enum(n).optional().catch(void 0),
20
- dashboardId: o,
21
- dashboardTitle: i,
22
- sheetId: o,
23
- sheetTitle: i
24
- });
17
+ ], r = e.string().min(1).max(128), s = e.string().max(500), _ = e.array(e.string().max(500)).max(500), l = e.number().int().nonnegative(), y = e.string().refine((o) => new TextEncoder().encode(o).length <= 16 * 1024), E = e.object({
18
+ token_type: e.enum(["dashboard", "project"]),
19
+ token_purpose: e.enum(["embed", "console"]).optional(),
20
+ ttl_s: e.number().int().nonnegative().optional(),
21
+ embed_origin: e.string().max(2048).optional(),
22
+ initial_dashboard_id: r.optional(),
23
+ dashboard_title: s.optional(),
24
+ project_name: s.optional(),
25
+ user_verified: e.boolean(),
26
+ user_email: s.optional(),
27
+ user_display_name: s.optional(),
28
+ tenant_name: s.optional(),
29
+ role: e.string().max(128).optional(),
30
+ user_provisioned: e.boolean().optional(),
31
+ domain_access_mode: e.enum(["all", "none", "include", "exclude"]).optional(),
32
+ domain_ids: e.array(r).max(500).optional(),
33
+ rls_policy_names: _.optional(),
34
+ cls_policy_names: _.optional(),
35
+ has_sls: e.boolean().optional(),
36
+ security_param_keys: _.optional(),
37
+ timezone: e.string().max(128).optional(),
38
+ mcp_scopes: e.array(e.string().max(128)).max(64).optional(),
39
+ mcp_sql: e.boolean().optional(),
40
+ mcp_live: e.boolean().optional()
41
+ }).strict(), S = e.object({
42
+ requested_version: e.number().int().optional(),
43
+ served: e.enum(["current", "version"]).optional(),
44
+ dashboard_title: s.optional(),
45
+ project_name: s.optional(),
46
+ sheet_count: l.optional(),
47
+ card_count: l.optional()
48
+ }).strict(), T = e.object({
49
+ statement: e.enum(x),
50
+ duration_ms: e.number().nonnegative(),
51
+ outcome: e.enum(["succeeded", "failed", "cancelled"]),
52
+ rows: l.optional()
53
+ }).strict(), v = e.object({
54
+ data_service_calls: l,
55
+ query_run_id: r,
56
+ parent_query_run_id: r.optional(),
57
+ query_kind: e.enum(f).optional(),
58
+ statements: e.array(T).max(64),
59
+ trigger: e.enum(b).optional(),
60
+ card_title: s.optional(),
61
+ card_type: e.string().max(128).optional(),
62
+ project_name: s.optional(),
63
+ connection_name: s.optional(),
64
+ connection_type: e.string().max(128).optional(),
65
+ dialect: e.string().max(128).optional(),
66
+ dataset: s.optional(),
67
+ rows: l.optional(),
68
+ row_limit_exceeded: e.boolean().optional(),
69
+ sql_text: y.optional(),
70
+ sql_truncated: e.boolean().optional(),
71
+ sql_hash: e.string().regex(/^[0-9a-f]{64}$/).optional(),
72
+ input_ids_applied: e.array(r).max(500).optional(),
73
+ page: e.number().int().positive().optional(),
74
+ export_job_id: r.optional()
75
+ }).strict(), q = e.object({
76
+ tool: e.string().min(1).max(128),
77
+ args_json: y.optional(),
78
+ args_truncated: e.boolean().optional(),
79
+ arg_keys: e.array(e.string().max(128)).max(200),
80
+ user_agent: e.string().max(1024).optional(),
81
+ oauth_client: s.optional(),
82
+ credential: e.string().max(64).optional(),
83
+ access_mode: e.string().max(64).optional(),
84
+ scopes: e.array(e.string().max(128)).max(64).optional(),
85
+ response_bytes: l.optional()
86
+ }).strict(), A = ["token_issued", "dashboard_opened", "query_executed", "tool_called"], U = ["usage", "runtime", "agent", "delivery"], k = ["org_user", "tenant_user", "tenant", "api_key", "system", "anonymous"], j = ["console", "embed", "public_link", "mcp", "api", "scheduler", "pdf_renderer"], I = ["succeeded", "failed", "cancelled", "timed_out"], G = ["app", "scheduler"], R = {
87
+ token_issued: {
88
+ category: "usage",
89
+ version: 1,
90
+ emittedBy: "semaphor-app/src/lib/usage-events/token-issued.ts",
91
+ personalData: !0,
92
+ detailsSchema: E
93
+ },
94
+ dashboard_opened: {
95
+ category: "usage",
96
+ version: 1,
97
+ emittedBy: "semaphor-app/src/lib/usage-events/dashboard-opened.ts",
98
+ personalData: !1,
99
+ detailsSchema: S
100
+ },
101
+ query_executed: {
102
+ category: "runtime",
103
+ version: 1,
104
+ emittedBy: "semaphor-app/src/app/api/v1/query/query-run.ts",
105
+ // sql_text holds the filter and control values the app compiled in.
106
+ personalData: !0,
107
+ detailsSchema: v
108
+ },
109
+ tool_called: {
110
+ category: "agent",
111
+ version: 1,
112
+ emittedBy: "semaphor-app/src/lib/mcp/tool-telemetry.ts",
113
+ // args_json is what the agent sent.
114
+ personalData: !0,
115
+ detailsSchema: q
116
+ }
117
+ }, D = 128, w = 500, p = e.string().max(D).optional().catch(void 0), g = e.string().max(w).optional().catch(void 0), P = e.object({
118
+ operationId: p,
119
+ trigger: e.enum(b).optional().catch(void 0),
120
+ dashboardId: p,
121
+ dashboardTitle: g,
122
+ sheetId: p,
123
+ sheetTitle: g
124
+ }), N = 16 * 1024, O = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/, C = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$/, B = e.string().min(1).max(128), a = B.nullable(), Y = e.object({
125
+ event_id: e.string().regex(O),
126
+ event_type: e.enum(A),
127
+ event_version: e.number().int().positive(),
128
+ category: e.enum(U),
129
+ occurred_at: e.string().regex(C),
130
+ producer: e.enum(G),
131
+ release: e.string().min(1).max(64),
132
+ org_id: a,
133
+ project_id: a,
134
+ tenant_id: a,
135
+ actor_type: e.enum(k),
136
+ org_user_id: a,
137
+ tenant_user_id: a,
138
+ surface: e.enum(j),
139
+ session_id: a,
140
+ operation_id: a,
141
+ dashboard_id: a,
142
+ sheet_id: a,
143
+ card_id: a,
144
+ connection_id: a,
145
+ domain_id: a,
146
+ outcome: e.enum(I).nullable(),
147
+ duration_ms: e.number().nonnegative().nullable(),
148
+ error: e.object({
149
+ code: e.string().min(1).max(128),
150
+ message: e.string().refine((o) => new TextEncoder().encode(o).length <= N)
151
+ }).strict().nullable(),
152
+ details: e.unknown()
153
+ }).strict();
154
+ function V(o) {
155
+ const n = Y.safeParse(o);
156
+ if (!n.success) return { ok: !1, issues: h(n.error.issues) };
157
+ const t = n.data, d = t.event_type, c = R[d], i = [];
158
+ t.event_version !== c.version && i.push("event_version: not the catalog version"), t.category !== c.category && i.push("category: not the catalog category");
159
+ const m = t.outcome === "failed" || t.outcome === "timed_out";
160
+ m && t.error === null && i.push("error: required when the outcome is failed or timed_out"), !m && t.error !== null && i.push("error: set only when the outcome is failed or timed_out"), t.org_id === null && !(d === "token_issued" && t.outcome === "failed") && i.push("org_id: null only on a refused token_issued"), i.push(...$[d](t));
161
+ const u = c.detailsSchema.safeParse(t.details);
162
+ return u.success || i.push(...h(u.error.issues, "details")), i.length > 0 ? { ok: !1, issues: i } : { ok: !0, event: { ...t, details: u.success ? u.data : t.details } };
163
+ }
164
+ const $ = {
165
+ token_issued: (o) => {
166
+ const n = [];
167
+ return ["org_user", "tenant_user", "tenant", "anonymous"].includes(o.actor_type) || n.push("actor_type: not a token_issued actor"), ["embed", "console", "mcp"].includes(o.surface) || n.push("surface: not a token_issued surface"), o.outcome === null && n.push("outcome: required"), o.outcome === "succeeded" && (o.session_id === null && n.push("session_id: required on success"), o.project_id === null && n.push("project_id: required on success")), n;
168
+ },
169
+ dashboard_opened: (o) => [
170
+ ...o.outcome === null ? ["outcome: required"] : [],
171
+ ...o.duration_ms === null ? ["duration_ms: required"] : [],
172
+ ...o.dashboard_id === null ? ["dashboard_id: required"] : []
173
+ ],
174
+ query_executed: (o) => [
175
+ ...o.outcome === null ? ["outcome: required"] : [],
176
+ ...o.duration_ms === null ? ["duration_ms: required"] : []
177
+ ],
178
+ tool_called: (o) => [
179
+ ...o.outcome === null ? ["outcome: required"] : [],
180
+ ...o.duration_ms === null ? ["duration_ms: required"] : [],
181
+ ...o.operation_id === null ? ["operation_id: required"] : []
182
+ ]
183
+ };
184
+ function h(o, n) {
185
+ return o.map((t) => `${[n, ...t.path].filter((c) => c !== void 0).join(".") || "(root)"}: ${t.code}`);
186
+ }
25
187
  export {
26
- r as QUERY_KINDS,
27
- s as QUERY_STATEMENTS,
28
- n as QUERY_TRIGGERS,
29
- a as USAGE_ATTRIBUTION_ID_MAX_LENGTH,
30
- c as USAGE_ATTRIBUTION_TITLE_MAX_LENGTH,
31
- l as usageAttributionFieldsSchema
188
+ f as QUERY_KINDS,
189
+ x as QUERY_STATEMENTS,
190
+ b as QUERY_TRIGGERS,
191
+ k as USAGE_ACTOR_TYPES,
192
+ D as USAGE_ATTRIBUTION_ID_MAX_LENGTH,
193
+ w as USAGE_ATTRIBUTION_TITLE_MAX_LENGTH,
194
+ R as USAGE_EVENT_CATALOG,
195
+ U as USAGE_EVENT_CATEGORIES,
196
+ N as USAGE_EVENT_TEXT_MAX_BYTES,
197
+ A as USAGE_EVENT_TYPES,
198
+ I as USAGE_OUTCOMES,
199
+ G as USAGE_PRODUCERS,
200
+ j as USAGE_SURFACES,
201
+ S as dashboardOpenedDetailsSchema,
202
+ V as parseUsageEvent,
203
+ v as queryExecutedDetailsSchema,
204
+ T as queryStatementRecordSchema,
205
+ E as tokenIssuedDetailsSchema,
206
+ q as toolCalledDetailsSchema,
207
+ P as usageAttributionFieldsSchema,
208
+ Y as usageEventEnvelopeSchema
32
209
  };
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  "email": "support@semaphor.cloud"
6
6
  },
7
7
  "license": "MIT",
8
- "version": "0.1.574",
8
+ "version": "0.1.575",
9
9
  "description": "Fully interactive and customizable dashboards for your apps.",
10
10
  "keywords": [
11
11
  "react",