@tracelog/event-contract 1.0.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/CHANGELOG.md ADDED
@@ -0,0 +1,36 @@
1
+ # Changelog
2
+
3
+ Every published version of `@tracelog/event-contract`, and what changed for
4
+ whoever sends or receives the envelope.
5
+
6
+ **What the numbers mean.** The major changes when a batch that was accepted
7
+ stops being accepted: a field removed or renamed, a limit lowered, a schema
8
+ narrowed, or `EVENT_ENVELOPE_VERSION` moving. Everything else is a minor or a
9
+ patch.
10
+
11
+ **An envelope version is a deploy before it is a release.** What a runtime
12
+ writes is the constant; what ingestion accepts is a set. The set widens and
13
+ deploys first, then this package and the runtimes built from it publish, then
14
+ the artifacts re-pin — because a page pinned to an old runtime keeps sending
15
+ the old value for as long as somebody serves it, and there is no `latest` to
16
+ carry it forward.
17
+
18
+ This package, `@tracelog/capture-core` and `@tracelog/capture-web` carry one
19
+ number between them.
20
+
21
+ ## 1.0.0
22
+
23
+ The first published envelope, extracted from the monorepo TraceLog was built in
24
+ and unchanged in behaviour by the extraction.
25
+
26
+ **`EVENT_ENVELOPE_VERSION` is `1`.**
27
+
28
+ **The limits**, as the endpoint enforces them: 50 events to a batch, 256 KiB to
29
+ a batch, 8 KiB of context to an event, 1 KiB to an error message, five minutes
30
+ of tolerance for a clock ahead of the server's, and seven days after which an
31
+ event is late rather than wrong.
32
+
33
+ **The schemas**, in zod, for the envelope and each event in it, with
34
+ `validateEventBatch`, which accepts a batch whole — flagging each event that
35
+ arrived late — or refuses it whole with one classification, so a refusal has a
36
+ reason the sender can read rather than a count.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 TraceLog
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,42 @@
1
+ # @tracelog/event-contract
2
+
3
+ The TraceLog event envelope: one definition of the wire format, its limits and
4
+ its schemas. The capture runtime is built from it and TraceLog's ingestion
5
+ validates every batch against it, so a field means the same thing on both sides
6
+ of the wire. Two definitions of one wire format drift, and drift at the wire is
7
+ silent data loss.
8
+
9
+ **This package is published so that the SDK's source can be read**, which
10
+ wordpress.org requires of the plugin bundle, and so that anything sending
11
+ TraceLog events from a runtime of its own can be checked against the same
12
+ schemas rather than a copy of them. Sites installing TraceLog do not need it:
13
+ `@tracelog/capture-web` carries the limits it uses inside its bundle.
14
+
15
+ <https://tracelog.io>
16
+
17
+ ## Install
18
+
19
+ <!-- x-release-please-start-version -->
20
+
21
+ ```bash
22
+ npm install @tracelog/event-contract@1.0.0
23
+ ```
24
+
25
+ <!-- x-release-please-end -->
26
+
27
+ ## What it holds
28
+
29
+ - **`EVENT_ENVELOPE_VERSION`** — the `v` a batch carries. What a runtime writes
30
+ is this constant; what ingestion accepts is a set, which only ever grows, so
31
+ a page pinned to an old runtime keeps being accepted.
32
+ - **The limits** — batch events, batch bytes, context bytes, error-message
33
+ bytes, the tolerance for a clock ahead of the server, and when an event is
34
+ late rather than wrong.
35
+ - **The schemas** — zod, for the envelope and every event in it, plus
36
+ `validateEventBatch`, which accepts a batch whole — flagging each event that
37
+ arrived late — or refuses it whole, with one classification the sender can
38
+ read.
39
+
40
+ ## Licence
41
+
42
+ MIT. See [LICENSE](./LICENSE).
@@ -0,0 +1,234 @@
1
+ import { z } from "zod";
2
+ export declare const EVENT_ENVELOPE_VERSION: 1;
3
+ export declare const MAX_BATCH_EVENTS = 50;
4
+ export declare const MAX_BATCH_BYTES: number;
5
+ export declare const MAX_CONTEXT_BYTES: number;
6
+ export declare const MAX_ERROR_MESSAGE_BYTES = 1024;
7
+ export declare const FUTURE_TOLERANCE_MS: number;
8
+ export declare const LATE_AFTER_MS: number;
9
+ export declare const eventIdSchema: z.ZodUUID;
10
+ export declare const sessionIdSchema: z.ZodUUID;
11
+ export declare const eventNameSchema: z.ZodString;
12
+ export declare const occurredAtSchema: z.ZodISODateTime;
13
+ export declare const eventModeSchema: z.ZodLiteral<"verification">;
14
+ export declare const contextSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
15
+ export declare const utmSchema: z.ZodObject<{
16
+ source: z.ZodOptional<z.ZodString>;
17
+ medium: z.ZodOptional<z.ZodString>;
18
+ campaign: z.ZodOptional<z.ZodString>;
19
+ term: z.ZodOptional<z.ZodString>;
20
+ content: z.ZodOptional<z.ZodString>;
21
+ }, z.core.$strict>;
22
+ export declare const deviceSchema: z.ZodEnum<{
23
+ desktop: "desktop";
24
+ mobile: "mobile";
25
+ tablet: "tablet";
26
+ }>;
27
+ export declare const sessionStartEventSchema: z.ZodObject<{
28
+ kind: z.ZodLiteral<"session_start">;
29
+ referrer: z.ZodOptional<z.ZodString>;
30
+ utm: z.ZodObject<{
31
+ source: z.ZodOptional<z.ZodString>;
32
+ medium: z.ZodOptional<z.ZodString>;
33
+ campaign: z.ZodOptional<z.ZodString>;
34
+ term: z.ZodOptional<z.ZodString>;
35
+ content: z.ZodOptional<z.ZodString>;
36
+ }, z.core.$strict>;
37
+ landingPage: z.ZodString;
38
+ device: z.ZodEnum<{
39
+ desktop: "desktop";
40
+ mobile: "mobile";
41
+ tablet: "tablet";
42
+ }>;
43
+ eventId: z.ZodUUID;
44
+ sessionId: z.ZodUUID;
45
+ name: z.ZodString;
46
+ occurredAt: z.ZodISODateTime;
47
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
48
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
49
+ }, z.core.$strict>;
50
+ export declare const stepEventSchema: z.ZodObject<{
51
+ kind: z.ZodLiteral<"step">;
52
+ eventId: z.ZodUUID;
53
+ sessionId: z.ZodUUID;
54
+ name: z.ZodString;
55
+ occurredAt: z.ZodISODateTime;
56
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
57
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
58
+ }, z.core.$strict>;
59
+ export declare const currencySchema: z.ZodString;
60
+ export declare const conversionEventSchema: z.ZodObject<{
61
+ kind: z.ZodLiteral<"conversion">;
62
+ identifier: z.ZodString;
63
+ value: z.ZodOptional<z.ZodNumber>;
64
+ currency: z.ZodOptional<z.ZodString>;
65
+ eventId: z.ZodUUID;
66
+ sessionId: z.ZodUUID;
67
+ name: z.ZodString;
68
+ occurredAt: z.ZodISODateTime;
69
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
70
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
71
+ }, z.core.$strict>;
72
+ export declare const errorMessageSchema: z.ZodString;
73
+ export declare const errorEventSchema: z.ZodObject<{
74
+ kind: z.ZodLiteral<"error">;
75
+ message: z.ZodString;
76
+ stepName: z.ZodString;
77
+ eventId: z.ZodUUID;
78
+ sessionId: z.ZodUUID;
79
+ name: z.ZodString;
80
+ occurredAt: z.ZodISODateTime;
81
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
82
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
83
+ }, z.core.$strict>;
84
+ export declare const eventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
85
+ kind: z.ZodLiteral<"session_start">;
86
+ referrer: z.ZodOptional<z.ZodString>;
87
+ utm: z.ZodObject<{
88
+ source: z.ZodOptional<z.ZodString>;
89
+ medium: z.ZodOptional<z.ZodString>;
90
+ campaign: z.ZodOptional<z.ZodString>;
91
+ term: z.ZodOptional<z.ZodString>;
92
+ content: z.ZodOptional<z.ZodString>;
93
+ }, z.core.$strict>;
94
+ landingPage: z.ZodString;
95
+ device: z.ZodEnum<{
96
+ desktop: "desktop";
97
+ mobile: "mobile";
98
+ tablet: "tablet";
99
+ }>;
100
+ eventId: z.ZodUUID;
101
+ sessionId: z.ZodUUID;
102
+ name: z.ZodString;
103
+ occurredAt: z.ZodISODateTime;
104
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
105
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
106
+ }, z.core.$strict>, z.ZodObject<{
107
+ kind: z.ZodLiteral<"step">;
108
+ eventId: z.ZodUUID;
109
+ sessionId: z.ZodUUID;
110
+ name: z.ZodString;
111
+ occurredAt: z.ZodISODateTime;
112
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
113
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
114
+ }, z.core.$strict>, z.ZodObject<{
115
+ kind: z.ZodLiteral<"conversion">;
116
+ identifier: z.ZodString;
117
+ value: z.ZodOptional<z.ZodNumber>;
118
+ currency: z.ZodOptional<z.ZodString>;
119
+ eventId: z.ZodUUID;
120
+ sessionId: z.ZodUUID;
121
+ name: z.ZodString;
122
+ occurredAt: z.ZodISODateTime;
123
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
124
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
125
+ }, z.core.$strict>, z.ZodObject<{
126
+ kind: z.ZodLiteral<"error">;
127
+ message: z.ZodString;
128
+ stepName: z.ZodString;
129
+ eventId: z.ZodUUID;
130
+ sessionId: z.ZodUUID;
131
+ name: z.ZodString;
132
+ occurredAt: z.ZodISODateTime;
133
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
134
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
135
+ }, z.core.$strict>], "kind">;
136
+ export declare const eventBatchSchema: z.ZodObject<{
137
+ v: z.ZodLiteral<1>;
138
+ events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
139
+ kind: z.ZodLiteral<"session_start">;
140
+ referrer: z.ZodOptional<z.ZodString>;
141
+ utm: z.ZodObject<{
142
+ source: z.ZodOptional<z.ZodString>;
143
+ medium: z.ZodOptional<z.ZodString>;
144
+ campaign: z.ZodOptional<z.ZodString>;
145
+ term: z.ZodOptional<z.ZodString>;
146
+ content: z.ZodOptional<z.ZodString>;
147
+ }, z.core.$strict>;
148
+ landingPage: z.ZodString;
149
+ device: z.ZodEnum<{
150
+ desktop: "desktop";
151
+ mobile: "mobile";
152
+ tablet: "tablet";
153
+ }>;
154
+ eventId: z.ZodUUID;
155
+ sessionId: z.ZodUUID;
156
+ name: z.ZodString;
157
+ occurredAt: z.ZodISODateTime;
158
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
159
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
160
+ }, z.core.$strict>, z.ZodObject<{
161
+ kind: z.ZodLiteral<"step">;
162
+ eventId: z.ZodUUID;
163
+ sessionId: z.ZodUUID;
164
+ name: z.ZodString;
165
+ occurredAt: z.ZodISODateTime;
166
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
167
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
168
+ }, z.core.$strict>, z.ZodObject<{
169
+ kind: z.ZodLiteral<"conversion">;
170
+ identifier: z.ZodString;
171
+ value: z.ZodOptional<z.ZodNumber>;
172
+ currency: z.ZodOptional<z.ZodString>;
173
+ eventId: z.ZodUUID;
174
+ sessionId: z.ZodUUID;
175
+ name: z.ZodString;
176
+ occurredAt: z.ZodISODateTime;
177
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
178
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
179
+ }, z.core.$strict>, z.ZodObject<{
180
+ kind: z.ZodLiteral<"error">;
181
+ message: z.ZodString;
182
+ stepName: z.ZodString;
183
+ eventId: z.ZodUUID;
184
+ sessionId: z.ZodUUID;
185
+ name: z.ZodString;
186
+ occurredAt: z.ZodISODateTime;
187
+ mode: z.ZodOptional<z.ZodLiteral<"verification">>;
188
+ context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
189
+ }, z.core.$strict>], "kind">>;
190
+ }, z.core.$strict>;
191
+ export declare const validationClassSchema: z.ZodEnum<{
192
+ unknown_version: "unknown_version";
193
+ invalid_schema: "invalid_schema";
194
+ too_large: "too_large";
195
+ future_time: "future_time";
196
+ late: "late";
197
+ }>;
198
+ export declare const rejectionClassSchema: z.ZodEnum<{
199
+ unknown_version: "unknown_version";
200
+ invalid_schema: "invalid_schema";
201
+ too_large: "too_large";
202
+ future_time: "future_time";
203
+ }>;
204
+ export type EventId = z.infer<typeof eventIdSchema>;
205
+ export type SessionId = z.infer<typeof sessionIdSchema>;
206
+ export type EventName = z.infer<typeof eventNameSchema>;
207
+ export type EventMode = z.infer<typeof eventModeSchema>;
208
+ export type EventContext = z.infer<typeof contextSchema>;
209
+ export type Utm = z.infer<typeof utmSchema>;
210
+ export type Device = z.infer<typeof deviceSchema>;
211
+ export type SessionStartEvent = z.infer<typeof sessionStartEventSchema>;
212
+ export type StepEvent = z.infer<typeof stepEventSchema>;
213
+ export type ConversionEvent = z.infer<typeof conversionEventSchema>;
214
+ export type ErrorEvent = z.infer<typeof errorEventSchema>;
215
+ export type Event = z.infer<typeof eventSchema>;
216
+ export type EventBatch = z.infer<typeof eventBatchSchema>;
217
+ export type ValidationClass = z.infer<typeof validationClassSchema>;
218
+ export type RejectionClass = z.infer<typeof rejectionClassSchema>;
219
+ export interface LateEventFlag {
220
+ classification: "late";
221
+ eventId: EventId;
222
+ }
223
+ export type EventBatchValidationResult = {
224
+ accepted: true;
225
+ batch: EventBatch;
226
+ flags: readonly LateEventFlag[];
227
+ } | {
228
+ accepted: false;
229
+ classification: RejectionClass;
230
+ };
231
+ export declare function validateEventBatch(input: unknown, clock: {
232
+ now(): Date;
233
+ }): EventBatchValidationResult;
234
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/dist/index.js ADDED
@@ -0,0 +1,133 @@
1
+ import { z } from "zod";
2
+ export const EVENT_ENVELOPE_VERSION = 1;
3
+ export const MAX_BATCH_EVENTS = 50;
4
+ export const MAX_BATCH_BYTES = 256 * 1024;
5
+ export const MAX_CONTEXT_BYTES = 8 * 1024;
6
+ export const MAX_ERROR_MESSAGE_BYTES = 1024;
7
+ export const FUTURE_TOLERANCE_MS = 5 * 60 * 1000;
8
+ export const LATE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
9
+ const textEncoder = new TextEncoder();
10
+ function utf8ByteLength(value) {
11
+ return textEncoder.encode(value).byteLength;
12
+ }
13
+ function serializedByteLength(value) {
14
+ try {
15
+ const serialized = JSON.stringify(value);
16
+ return serialized === undefined ? undefined : utf8ByteLength(serialized);
17
+ }
18
+ catch {
19
+ return undefined;
20
+ }
21
+ }
22
+ export const eventIdSchema = z.uuidv7();
23
+ export const sessionIdSchema = z.uuidv7();
24
+ export const eventNameSchema = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
25
+ export const occurredAtSchema = z.iso.datetime({ precision: 3 });
26
+ export const eventModeSchema = z.literal("verification");
27
+ export const contextSchema = z
28
+ .record(z.string(), z.json())
29
+ .refine((context) => (serializedByteLength(context) ?? Number.POSITIVE_INFINITY) <=
30
+ MAX_CONTEXT_BYTES, { message: `context must serialize to at most ${MAX_CONTEXT_BYTES} bytes` });
31
+ const commonEventFields = {
32
+ eventId: eventIdSchema,
33
+ sessionId: sessionIdSchema,
34
+ name: eventNameSchema,
35
+ occurredAt: occurredAtSchema,
36
+ mode: eventModeSchema.optional(),
37
+ context: contextSchema.optional(),
38
+ };
39
+ export const utmSchema = z.strictObject({
40
+ source: z.string().optional(),
41
+ medium: z.string().optional(),
42
+ campaign: z.string().optional(),
43
+ term: z.string().optional(),
44
+ content: z.string().optional(),
45
+ });
46
+ export const deviceSchema = z.enum(["desktop", "mobile", "tablet"]);
47
+ export const sessionStartEventSchema = z.strictObject({
48
+ ...commonEventFields,
49
+ kind: z.literal("session_start"),
50
+ referrer: z.string().optional(),
51
+ utm: utmSchema,
52
+ landingPage: z.string(),
53
+ device: deviceSchema,
54
+ });
55
+ export const stepEventSchema = z.strictObject({
56
+ ...commonEventFields,
57
+ kind: z.literal("step"),
58
+ });
59
+ export const currencySchema = z.string().regex(/^[A-Z]{3}$/);
60
+ export const conversionEventSchema = z.strictObject({
61
+ ...commonEventFields,
62
+ kind: z.literal("conversion"),
63
+ identifier: z.string().min(1).max(256),
64
+ value: z.number().nonnegative().optional(),
65
+ currency: currencySchema.optional(),
66
+ });
67
+ export const errorMessageSchema = z
68
+ .string()
69
+ .refine((message) => utf8ByteLength(message) <= MAX_ERROR_MESSAGE_BYTES, {
70
+ message: `message must be at most ${MAX_ERROR_MESSAGE_BYTES} bytes`,
71
+ });
72
+ export const errorEventSchema = z.strictObject({
73
+ ...commonEventFields,
74
+ kind: z.literal("error"),
75
+ message: errorMessageSchema,
76
+ stepName: eventNameSchema,
77
+ });
78
+ export const eventSchema = z.discriminatedUnion("kind", [
79
+ sessionStartEventSchema,
80
+ stepEventSchema,
81
+ conversionEventSchema,
82
+ errorEventSchema,
83
+ ]);
84
+ export const eventBatchSchema = z.strictObject({
85
+ v: z.literal(EVENT_ENVELOPE_VERSION),
86
+ events: z.array(eventSchema).max(MAX_BATCH_EVENTS),
87
+ });
88
+ export const validationClassSchema = z.enum([
89
+ "unknown_version",
90
+ "invalid_schema",
91
+ "too_large",
92
+ "future_time",
93
+ "late",
94
+ ]);
95
+ export const rejectionClassSchema = z.enum([
96
+ "unknown_version",
97
+ "invalid_schema",
98
+ "too_large",
99
+ "future_time",
100
+ ]);
101
+ function hasUnknownNumericVersion(input) {
102
+ return (typeof input === "object" &&
103
+ input !== null &&
104
+ "v" in input &&
105
+ typeof input.v === "number" &&
106
+ input.v !== EVENT_ENVELOPE_VERSION);
107
+ }
108
+ export function validateEventBatch(input, clock) {
109
+ const bodyBytes = serializedByteLength(input);
110
+ if (bodyBytes !== undefined && bodyBytes > MAX_BATCH_BYTES) {
111
+ return { accepted: false, classification: "too_large" };
112
+ }
113
+ if (hasUnknownNumericVersion(input)) {
114
+ return { accepted: false, classification: "unknown_version" };
115
+ }
116
+ const parsed = eventBatchSchema.safeParse(input);
117
+ if (!parsed.success) {
118
+ return { accepted: false, classification: "invalid_schema" };
119
+ }
120
+ const now = clock.now().getTime();
121
+ const flags = [];
122
+ for (const event of parsed.data.events) {
123
+ const occurredAt = new Date(event.occurredAt).getTime();
124
+ if (occurredAt > now + FUTURE_TOLERANCE_MS) {
125
+ return { accepted: false, classification: "future_time" };
126
+ }
127
+ if (occurredAt < now - LATE_AFTER_MS) {
128
+ flags.push({ classification: "late", eventId: event.eventId });
129
+ }
130
+ }
131
+ return { accepted: true, batch: parsed.data, flags };
132
+ }
133
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC;AACjD,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AACjD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAErD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC;AAC9C,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;AACxC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;AAC1C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;KAC5B,MAAM,CACL,CAAC,OAAO,EAAE,EAAE,CACV,CAAC,oBAAoB,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAC3D,iBAAiB,EACnB,EAAE,OAAO,EAAE,qCAAqC,iBAAiB,QAAQ,EAAE,CAC5E,CAAC;AAEJ,MAAM,iBAAiB,GAAG;IACxB,OAAO,EAAE,aAAa;IACtB,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,eAAe;IACrB,UAAU,EAAE,gBAAgB;IAC5B,IAAI,EAAE,eAAe,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE;CAClC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC;IACtC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,YAAY,CAAC;IACpD,GAAG,iBAAiB;IACpB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,GAAG,EAAE,SAAS;IACd,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,YAAY;CACrB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5C,GAAG,iBAAiB;IACpB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,YAAY,CAAC;IAClD,GAAG,iBAAiB;IACpB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC1C,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,EAAE;KACR,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,uBAAuB,EAAE;IACvE,OAAO,EAAE,2BAA2B,uBAAuB,QAAQ;CACpE,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC7C,GAAG,iBAAiB;IACpB,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,OAAO,EAAE,kBAAkB;IAC3B,QAAQ,EAAE,eAAe;CAC1B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACtD,uBAAuB;IACvB,eAAe;IACf,qBAAqB;IACrB,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC7C,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;CACnD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1C,iBAAiB;IACjB,gBAAgB;IAChB,WAAW;IACX,aAAa;IACb,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC;IACzC,iBAAiB;IACjB,gBAAgB;IAChB,WAAW;IACX,aAAa;CACd,CAAC,CAAC;AAkCH,SAAS,wBAAwB,CAAC,KAAc;IAC9C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,GAAG,IAAI,KAAK;QACZ,OAAO,KAAK,CAAC,CAAC,KAAK,QAAQ;QAC3B,KAAK,CAAC,CAAC,KAAK,sBAAsB,CACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,KAAsB;IAEtB,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,eAAe,EAAE,CAAC;QAC3D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC;IAC1D,CAAC;IAED,IAAI,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAClC,MAAM,KAAK,GAAoB,EAAE,CAAC;IAElC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;QACxD,IAAI,UAAU,GAAG,GAAG,GAAG,mBAAmB,EAAE,CAAC;YAC3C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC;QAC5D,CAAC;QAED,IAAI,UAAU,GAAG,GAAG,GAAG,aAAa,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC"}
package/package.json ADDED
@@ -0,0 +1,48 @@
1
+ {
2
+ "name": "@tracelog/event-contract",
3
+ "version": "1.0.0",
4
+ "description": "The TraceLog event envelope: one definition of the wire format, its limits and its schemas.",
5
+ "keywords": [
6
+ "conversion",
7
+ "conversion-tracking",
8
+ "schema",
9
+ "zod",
10
+ "wire-format"
11
+ ],
12
+ "homepage": "https://tracelog.io",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/nacorga/tracelog-sdk.git",
16
+ "directory": "packages/event-contract"
17
+ },
18
+ "bugs": {
19
+ "url": "https://github.com/nacorga/tracelog-sdk/issues"
20
+ },
21
+ "license": "MIT",
22
+ "type": "module",
23
+ "sideEffects": false,
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.ts",
27
+ "default": "./dist/index.js"
28
+ },
29
+ "./package.json": "./package.json"
30
+ },
31
+ "files": [
32
+ "dist",
33
+ "README.md",
34
+ "CHANGELOG.md",
35
+ "LICENSE"
36
+ ],
37
+ "publishConfig": {
38
+ "access": "public"
39
+ },
40
+ "dependencies": {
41
+ "zod": "4.4.3"
42
+ },
43
+ "scripts": {
44
+ "build": "tsc -p tsconfig.build.json",
45
+ "test": "vitest run",
46
+ "typecheck": "tsc -p tsconfig.json"
47
+ }
48
+ }