@ihyeon/browser-error-log-protocol 0.0.0-stage → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyeonse Im
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,46 @@
+# @ihyeon/browser-error-log-protocol
+
+[English](https://github.com/hyeonse-swing/browser-error-log/blob/main/packages/protocol/README.md) | 한국어
+
+Browser Error Log SDK·수집기·뷰어를 위한 버전이 있는 TypeScript 계약입니다. SDK를 자체 백엔드에 연결하거나 뷰어 데이터 소스를 구현할 때 사용하세요.
+
+직접 사용하는 경우 설치합니다. `@ihyeon/browser-error-log`도 의존성으로 포함합니다.
+
+```sh
+npm install @ihyeon/browser-error-log-protocol
+```
+
+게시 패키지 대신 로컬 소스 tarball을 사용하려면 Node.js 24에서 `npm ci`, `npm run check:package`를 실행하고 `output/packages/ihyeon-browser-error-log-protocol-0.1.6.tgz`를 절대 경로로 설치합니다. [SDK 가이드](https://github.com/hyeonse-swing/browser-error-log/blob/main/docs/ko/personal-sdk.md)를 참고하세요.
+
+## 이벤트·조회 계약
+
+```ts
+import {
+  SCHEMA_VERSION,
+  EVENT_LABELS,
+  type ErrorEventRecord,
+  type EventBatch,
+  type EventFilter,
+  type EventPage,
+  type EventDataSource,
+} from '@ihyeon/browser-error-log-protocol';
+
+function makeBatch(events: ErrorEventRecord[]): EventBatch {
+  return { schemaVersion: SCHEMA_VERSION, events };
+}
+```
+
+- `ErrorEventRecord`는 프로젝트·환경·릴리스·이벤트 ID·발생 시각·종류·메시지·페이지·런타임과 선택적인 스택·네트워크·context를 담는 v1 이벤트입니다.
+- `EventBatch`는 `{ schemaVersion: 1, events: [...] }`로 이벤트를 묶어 전송합니다.
+- `EventFilter`는 프로젝트·환경·종류·텍스트 검색·기간·커서·건수 제한을 지원합니다.
+- `EventPage`는 `events`와 선택적인 `nextCursor`를 반환합니다.
+- `EventDataSource`는 뷰어용 `listEvents(filter, signal?)`, `getEvent(project, eventId, signal?)`을 정의합니다.
+- `EVENT_LABELS`는 영어 표시 이름을 제공합니다. 이벤트 종류 식별자는 바뀌지 않습니다.
+
+이 패키지는 타입과 상수를 제공하며 런타임 검증기·DB·HTTP 서버는 아닙니다. 수집기의 입력은 신뢰할 수 없는 데이터로 보고 검증하세요. 중복 제거와 조회는 `(project, eventId)`로 범위를 정합니다. 다른 프로젝트에서 같은 eventId를 사용할 수 있습니다. ISO 시각을 사용하고 클라이언트의 `occurredAt`과 서버의 `receivedAt`을 구분하세요.
+
+[연동 계약](https://github.com/hyeonse-swing/browser-error-log/blob/main/docs/ko/integration.md)은 HTTP API를 설명합니다. `examples/micro-server`는 영속 SQLite 또는 로그 전용 JSONL 수집기를 구현합니다. 메모리 기반 개발 수집기는 데모입니다.
+
+## 호스팅과 비용
+
+인프라는 포함되지 않습니다. 호스팅, 서버, 데이터베이스, 스토리지, 대역폭, 도메인, 백업 및 제3자 서비스는 각 운영자가 선택하고 비용을 부담합니다. 요금은 해당 제공업체가 이 프로젝트 및 유지관리자와 독립적으로 청구합니다.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @ihyeon/browser-error-log-protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [한국어](https://github.com/hyeonse-swing/browser-error-log/blob/main/packages/protocol/README.ko.md)
+
+Versioned TypeScript contracts for Browser Error Log SDKs, collectors, and viewers. Use them when connecting the SDK to your own backend or implementing a viewer data source.
+
+Install directly when implementing your own collector or viewer; `@ihyeon/browser-error-log` also brings this package in as a dependency:
+
+```sh
+npm install @ihyeon/browser-error-log-protocol
+```
+
+For local source-checkout development, use Node.js 24, `npm ci`, and `npm run check:package`, then install `output/packages/ihyeon-browser-error-log-protocol-0.1.6.tgz` by absolute path. See the [SDK guide](https://github.com/hyeonse-swing/browser-error-log/blob/main/docs/personal-sdk.md).
+
+## Event and query contracts
+
+```ts
+import {
+  SCHEMA_VERSION,
+  EVENT_LABELS,
+  type ErrorEventRecord,
+  type EventBatch,
+  type EventFilter,
+  type EventPage,
+  type EventDataSource,
+} from '@ihyeon/browser-error-log-protocol';
+
+function makeBatch(events: ErrorEventRecord[]): EventBatch {
+  return { schemaVersion: SCHEMA_VERSION, events };
+}
+```
+
+- `ErrorEventRecord` describes a v1 event, including project, environment, release, event ID, occurrence time, type, message, page, runtime, and optional stack, network, and custom context fields.
+- `EventBatch` wraps events as `{ schemaVersion: 1, events: [...] }` for ingestion.
+- `EventFilter` supports project, environment, type, text query, time range, cursor, and limit.
+- `EventPage` returns `events` and an optional `nextCursor`.
+- `EventDataSource` exposes `listEvents(filter, signal?)` and `getEvent(project, eventId, signal?)` for the viewer.
+- `EVENT_LABELS` provides English display labels. The underlying event type identifiers stay unchanged.
+
+These are types and constants, not a runtime validator, database, or HTTP server. Treat all incoming data as untrusted and validate it at your collector. Scope deduplication and event lookup by `(project, eventId)`; different projects may use the same event ID. Use ISO timestamps and distinguish client-supplied `occurredAt` from server-owned `receivedAt`.
+
+The [integration contract](https://github.com/hyeonse-swing/browser-error-log/blob/main/docs/integration.md) describes the HTTP API; `examples/micro-server` implements a small self-hosted collector with persistent SQLite or log-only JSONL storage. The in-memory development collector is only a demo.
+
+## Hosting and costs
+
+Infrastructure is not included. Hosting, servers, databases, storage, bandwidth, domains, backups, and third-party services are selected and paid for by each operator. Any charges are billed independently by their providers, not by this project or its maintainers.

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var s=Object.defineProperty;var i=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var g=(r,e)=>{for(var n in e)s(r,n,{get:e[n],enumerable:!0})},p=(r,e,n,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of a(e))!c.call(r,t)&&t!==n&&s(r,t,{get:()=>e[t],enumerable:!(o=i(e,t))||o.enumerable});return r};var v=r=>p(s({},"__esModule",{value:!0}),r);var l={};g(l,{EVENT_LABELS:()=>u,SCHEMA_VERSION:()=>m,SDK_VERSION:()=>E});module.exports=v(l);var m=1,E="0.1.6",u={javascript:"JavaScript",promise:"Promise",react:"React",console:"Console",http:"HTTP error",network:"Network failure",manual:"Manual"};
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export const SCHEMA_VERSION = 1 as const;\nexport const SDK_VERSION = '0.1.6';\n\nexport type EventType = 'javascript' | 'promise' | 'react' | 'console' | 'http' | 'network' | 'manual';\nexport type Runtime = 'browser' | 'webview-ios' | 'webview-android' | 'unknown';\nexport interface ErrorEventRecord {\n  schemaVersion: 1;\n  eventId: string;\n  project: string;\n  environment: string;\n  release: string;\n  sdkVersion: string;\n  occurredAt: string;\n  receivedAt?: string;\n  viewId: string;\n  sequence: number;\n  elapsedMs: number;\n  type: EventType;\n  message: string;\n  name?: string;\n  stack?: string;\n  componentStack?: string;\n  page: string;\n  runtime: Runtime;\n  browser?: string;\n  context?: Record<string, string | number | boolean | null>;\n  network?: { method: string; url: string; status?: number; durationMs: number };\n}\n\nexport interface EventBatch { schemaVersion: 1; events: ErrorEventRecord[] }\nexport interface EventFilter {\n  project?: string;\n  environment?: string;\n  type?: EventType;\n  query?: string;\n  from?: string;\n  to?: string;\n  cursor?: string;\n  limit?: number;\n}\nexport interface EventPage { events: ErrorEventRecord[]; nextCursor?: string }\nexport interface EventDataSource {\n  listEvents(filter: EventFilter, signal?: AbortSignal): Promise<EventPage>;\n  getEvent(project: string, eventId: string, signal?: AbortSignal): Promise<ErrorEventRecord | null>;\n}\n\nexport const EVENT_LABELS: Record<EventType, string> = {\n  javascript: 'JavaScript', promise: 'Promise', react: 'React', console: 'Console',\n  http: 'HTTP error', network: 'Network failure', manual: 'Manual',\n};\n"],
+  "mappings": "yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,kBAAAE,EAAA,mBAAAC,EAAA,gBAAAC,IAAA,eAAAC,EAAAL,GAAO,IAAMG,EAAiB,EACjBC,EAAc,QA6CdF,EAA0C,CACrD,WAAY,aAAc,QAAS,UAAW,MAAO,QAAS,QAAS,UACvE,KAAM,aAAc,QAAS,kBAAmB,OAAQ,QAC1D",
+  "names": ["index_exports", "__export", "EVENT_LABELS", "SCHEMA_VERSION", "SDK_VERSION", "__toCommonJS"]
+}

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export declare const SCHEMA_VERSION: 1;
+export declare const SDK_VERSION = "0.1.6";
+export type EventType = 'javascript' | 'promise' | 'react' | 'console' | 'http' | 'network' | 'manual';
+export type Runtime = 'browser' | 'webview-ios' | 'webview-android' | 'unknown';
+export interface ErrorEventRecord {
+    schemaVersion: 1;
+    eventId: string;
+    project: string;
+    environment: string;
+    release: string;
+    sdkVersion: string;
+    occurredAt: string;
+    receivedAt?: string;
+    viewId: string;
+    sequence: number;
+    elapsedMs: number;
+    type: EventType;
+    message: string;
+    name?: string;
+    stack?: string;
+    componentStack?: string;
+    page: string;
+    runtime: Runtime;
+    browser?: string;
+    context?: Record<string, string | number | boolean | null>;
+    network?: {
+        method: string;
+        url: string;
+        status?: number;
+        durationMs: number;
+    };
+}
+export interface EventBatch {
+    schemaVersion: 1;
+    events: ErrorEventRecord[];
+}
+export interface EventFilter {
+    project?: string;
+    environment?: string;
+    type?: EventType;
+    query?: string;
+    from?: string;
+    to?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface EventPage {
+    events: ErrorEventRecord[];
+    nextCursor?: string;
+}
+export interface EventDataSource {
+    listEvents(filter: EventFilter, signal?: AbortSignal): Promise<EventPage>;
+    getEvent(project: string, eventId: string, signal?: AbortSignal): Promise<ErrorEventRecord | null>;
+}
+export declare const EVENT_LABELS: Record<EventType, string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/protocol/src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,EAAG,CAAU,CAAC;AACzC,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AACvG,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAChF,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AAED,MAAM,WAAW,UAAU;IAAG,aAAa,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,gBAAgB,EAAE,CAAA;CAAE;AAC5E,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE;AAC9E,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CACpG;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAGlD,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+var e=1,r="0.1.6",t={javascript:"JavaScript",promise:"Promise",react:"React",console:"Console",http:"HTTP error",network:"Network failure",manual:"Manual"};export{t as EVENT_LABELS,e as SCHEMA_VERSION,r as SDK_VERSION};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export const SCHEMA_VERSION = 1 as const;\nexport const SDK_VERSION = '0.1.6';\n\nexport type EventType = 'javascript' | 'promise' | 'react' | 'console' | 'http' | 'network' | 'manual';\nexport type Runtime = 'browser' | 'webview-ios' | 'webview-android' | 'unknown';\nexport interface ErrorEventRecord {\n  schemaVersion: 1;\n  eventId: string;\n  project: string;\n  environment: string;\n  release: string;\n  sdkVersion: string;\n  occurredAt: string;\n  receivedAt?: string;\n  viewId: string;\n  sequence: number;\n  elapsedMs: number;\n  type: EventType;\n  message: string;\n  name?: string;\n  stack?: string;\n  componentStack?: string;\n  page: string;\n  runtime: Runtime;\n  browser?: string;\n  context?: Record<string, string | number | boolean | null>;\n  network?: { method: string; url: string; status?: number; durationMs: number };\n}\n\nexport interface EventBatch { schemaVersion: 1; events: ErrorEventRecord[] }\nexport interface EventFilter {\n  project?: string;\n  environment?: string;\n  type?: EventType;\n  query?: string;\n  from?: string;\n  to?: string;\n  cursor?: string;\n  limit?: number;\n}\nexport interface EventPage { events: ErrorEventRecord[]; nextCursor?: string }\nexport interface EventDataSource {\n  listEvents(filter: EventFilter, signal?: AbortSignal): Promise<EventPage>;\n  getEvent(project: string, eventId: string, signal?: AbortSignal): Promise<ErrorEventRecord | null>;\n}\n\nexport const EVENT_LABELS: Record<EventType, string> = {\n  javascript: 'JavaScript', promise: 'Promise', react: 'React', console: 'Console',\n  http: 'HTTP error', network: 'Network failure', manual: 'Manual',\n};\n"],
+  "mappings": "AAAO,IAAMA,EAAiB,EACjBC,EAAc,QA6CdC,EAA0C,CACrD,WAAY,aAAc,QAAS,UAAW,MAAO,QAAS,QAAS,UACvE,KAAM,aAAc,QAAS,kBAAmB,OAAQ,QAC1D",
+  "names": ["SCHEMA_VERSION", "SDK_VERSION", "EVENT_LABELS"]
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@ihyeon/browser-error-log-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "Versioned event and query contracts for Browser Error Log collectors and viewers.",
+  "keywords": [
+    "error-monitoring",
+    "self-hosted",
+    "typescript",
+    "protocol"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ko.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyeonse-swing/browser-error-log.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://github.com/hyeonse-swing/browser-error-log#readme",
+  "bugs": {
+    "url": "https://github.com/hyeonse-swing/browser-error-log/issues"
+  }
+}