@tracewayapp/core 1.0.5 → 1.0.6

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 (2) hide show
  1. package/README.md +85 -11
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,32 @@
1
- # @tracewayapp/core
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tracewayapp/traceway/main/Traceway%20Logo%20White.png" />
4
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/tracewayapp/traceway/main/Traceway%20Logo.png" />
5
+ <img src="https://raw.githubusercontent.com/tracewayapp/traceway/main/Traceway%20Logo.png" alt="Traceway" width="200" />
6
+ </picture>
7
+ </p>
2
8
 
3
- Shared types and utilities for all Traceway JavaScript SDKs. Zero runtime dependencies.
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/@tracewayapp/core"><img src="https://img.shields.io/npm/v/@tracewayapp/core.svg" alt="npm"></a>
11
+ <a href="https://github.com/tracewayapp/traceway-js/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
12
+ </p>
13
+
14
+ # Traceway JS Core
15
+
16
+ Shared types and utilities consumed by every Traceway JavaScript SDK. Zero runtime dependencies, framework-agnostic, safe to import anywhere — browser, Node, React Native, Hermes, Cloudflare Workers.
17
+
18
+ [Traceway](https://tracewayapp.com) is a completely open-source error tracking platform. You can [self-host](https://docs.tracewayapp.com/server) it or use [Traceway Cloud](https://tracewayapp.com).
19
+
20
+ > **You probably don't need to install this directly.** It's a transitive dependency of `@tracewayapp/frontend`, `@tracewayapp/react-native`, and the framework wrappers. Install one of those instead. Reach for `@tracewayapp/core` directly only if you're building your own SDK or rendering Traceway's wire types in a dashboard.
21
+
22
+ ## Features
23
+
24
+ - Type definitions for the full Traceway wire format — exceptions, metrics, traces, spans, session recordings
25
+ - Discriminated union for the timeline event types (logs, network, navigation, custom breadcrumbs)
26
+ - A bounded rolling `EventBuffer<T>` keyed by time window + max size, used by every higher-level SDK to capture the last ~10 seconds of activity
27
+ - Connection-string parser, UUID v4 generator, ISO-8601 timestamp helper
28
+ - Constants for built-in metric names (`mem.used`, `cpu.used_pcnt`, etc.)
29
+ - Pure ESM + CJS dual output, full TypeScript declarations
4
30
 
5
31
  ## Installation
6
32
 
@@ -8,30 +34,57 @@ Shared types and utilities for all Traceway JavaScript SDKs. Zero runtime depend
8
34
  npm install @tracewayapp/core
9
35
  ```
10
36
 
11
- ## Types
37
+ ## Quick Start
38
+
39
+ ```ts
40
+ import {
41
+ parseConnectionString,
42
+ generateUUID,
43
+ nowISO,
44
+ EventBuffer,
45
+ type LogEvent,
46
+ type ReportRequest,
47
+ } from "@tracewayapp/core";
48
+
49
+ const { token, apiUrl } = parseConnectionString(
50
+ "your-token@https://traceway.example.com/api/report",
51
+ );
52
+
53
+ // Rolling buffer that drops entries older than 10s OR beyond 200 entries:
54
+ const logs = new EventBuffer<LogEvent>({ windowMs: 10_000, maxSize: 200 });
55
+ logs.add({
56
+ type: "log",
57
+ timestamp: nowISO(),
58
+ level: "info",
59
+ message: "user reached checkout",
60
+ });
61
+
62
+ const recent: LogEvent[] = logs.snapshot();
63
+ ```
64
+
65
+ ## Wire Types
12
66
 
13
67
  ### Reporting
14
68
 
15
69
  | Type | Description |
16
70
  |------|-------------|
17
- | `ExceptionStackTrace` | Exception/message record matching the Traceway protocol |
71
+ | `ExceptionStackTrace` | Single exception/message record |
18
72
  | `MetricRecord` | Metric data point (`name`, `value`, `recordedAt`, optional `tags`) |
19
73
  | `Span` | Sub-operation span within a trace |
20
74
  | `Trace` | Endpoint or task trace |
21
75
  | `CollectionFrame` | Batch of stack traces, metrics, traces, and session recordings |
22
76
  | `ReportRequest` | Top-level request payload sent to `/api/report` |
23
- | `TracewayOptions` | Configuration options for SDK initialization |
24
77
 
25
- ### Logs, Actions, and Session Recordings
78
+ ### Timeline (logs, actions, recordings)
26
79
 
27
- The frontend SDK ships a rolling timeline of logs and action breadcrumbs alongside each captured exception, plus an rrweb-based session replay. The wire types are defined here so other packages and dashboards can share them.
80
+ The browser, RN, and framework SDKs ship a rolling timeline of logs and action breadcrumbs alongside each captured exception. The wire types are defined here so dashboards and custom SDKs can share them.
28
81
 
29
82
  | Type | Description |
30
83
  |------|-------------|
31
84
  | `TracewayEventBase` | Discriminator (`type`) + `timestamp` shared by all timeline events |
32
- | `LogEvent` | Console log entry: `level` (`debug` / `info` / `warn` / `error`) + `message` |
85
+ | `LogEvent` | Console log: `level` (`debug` / `info` / `warn` / `error`) + `message` |
33
86
  | `NetworkEvent` | `fetch` / `XHR` request: `method`, `url`, `durationMs`, optional `statusCode`, byte counts, `error` |
34
- | `NavigationEvent` | History API transition: `action` (`push` / `replace` / `pop`), `from`, `to` |
87
+ | `NavigationEvent` | History API or manual navigation transition: `action` (`push` / `replace` / `pop`), `from`, `to` |
35
88
  | `CustomEvent` | User-defined breadcrumb from `recordAction(category, name, data?)` |
36
89
  | `TracewayEvent` | Discriminated union of the four event types above |
37
90
  | `SessionRecordingPayload` | Replay frames + buffered `logs` + `actions` + `startedAt` / `endedAt` anchors, attached to an exception via `exceptionId` |
@@ -40,11 +93,11 @@ The frontend SDK ships a rolling timeline of logs and action breadcrumbs alongsi
40
93
 
41
94
  | Function | Description |
42
95
  |----------|-------------|
96
+ | `parseConnectionString(str)` | Split `{token}@{apiUrl}` into `{ token, apiUrl }`; throws on malformed input |
43
97
  | `generateUUID()` | Generate a UUID v4 string |
44
- | `parseConnectionString(str)` | Split `{token}@{apiUrl}` into `{ token, apiUrl }` |
45
98
  | `nowISO()` | Current time as ISO 8601 string |
46
99
  | `msToNanoseconds(ms)` | Convert milliseconds to nanoseconds (integer) |
47
- | `EventBuffer<T>` | Bounded rolling buffer (`windowMs`, `maxSize`) used by the frontend SDK to keep the most recent logs and actions |
100
+ | `EventBuffer<T>` | Bounded rolling buffer (`windowMs`, `maxSize`) used by the higher-level SDKs to keep the most recent logs and actions |
48
101
 
49
102
  ## Constants
50
103
 
@@ -53,3 +106,24 @@ The frontend SDK ships a rolling timeline of logs and action breadcrumbs alongsi
53
106
  | `METRIC_MEM_USED` | `"mem.used"` |
54
107
  | `METRIC_MEM_TOTAL` | `"mem.total"` |
55
108
  | `METRIC_CPU_USED_PCNT` | `"cpu.used_pcnt"` |
109
+
110
+ ## Platform Support
111
+
112
+ | Environment | Status |
113
+ |---|---|
114
+ | Browser (any modern engine) | Yes |
115
+ | Node.js ≥ 18 | Yes |
116
+ | React Native (Hermes / JSC) | Yes |
117
+ | Cloudflare Workers / Deno / Bun | Yes |
118
+
119
+ ## Links
120
+
121
+ - [Traceway Website](https://tracewayapp.com)
122
+ - [Traceway GitHub](https://github.com/tracewayapp/traceway)
123
+ - [Documentation](https://docs.tracewayapp.com)
124
+ - [Browser SDK](https://www.npmjs.com/package/@tracewayapp/frontend)
125
+ - [React Native SDK](https://www.npmjs.com/package/@tracewayapp/react-native)
126
+
127
+ ## License
128
+
129
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracewayapp/core",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "Shared types and utilities for Traceway SDKs",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",