@sylphx/contract 0.2.0

package/dist/schemas/monitoring-admin.js

@@ -0,0 +1,196 @@
+/**
+ * Monitoring Admin — schemas for the Console error-tracking dashboard
+ * (list / detail / resolve / delete errors + source maps + stack-trace
+ * resolution).
+ *
+ * Mirrors `apps/api/src/server/platform/routes/monitoring/*`.
+ *
+ * Plane: `management`. Namespaced `-admin` to avoid collision with the
+ * BaaS-plane `monitoring` schemas (Sentry-style capture ingest served by
+ * the standalone runtime at `/sdk/monitoring/*`) — the dashboard viewing
+ * surface is Console-plane, the capture surface is BaaS-plane, and they
+ * share the `appErrors` per-project table only.
+ *
+ * Shape policy (Wave 3B):
+ *   - `metadata` on errors stays `Schema.Record` — freeform context bag
+ *     populated by the SDK's `captureException` call.
+ *   - `usageSummary`-style aggregated dashboard data uses nested
+ *     `Schema.Struct`s because the dashboard chart shapes are stable.
+ *   - Resolved stack frames inherit the resolver's shape verbatim
+ *     (`originalFilename`, `originalLine`, …) — the server library controls
+ *     the wire and the Console renders it.
+ */
+import { Schema } from 'effect';
+import { MonitoringSeverity } from './monitoring.js';
+// The BaaS monitoring namespace already exports the canonical severity
+// enum (`fatal | error | warning | info`). The Console dashboard reuses
+// the same shape — one SSOT, re-aliased for readability in this module.
+const Severity = MonitoringSeverity;
+// ── Path params ────────────────────────────────────────────────────────────
+export const MonitoringProjectPath = Schema.Struct({ id: Schema.String });
+export const ErrorIdParams = Schema.Struct({ errorId: Schema.String });
+// ── Common refs ────────────────────────────────────────────────────────────
+const ProjectRef = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    slug: Schema.String,
+});
+const EnvironmentRef = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    envType: Schema.String,
+});
+const ResolverRef = Schema.Struct({
+    id: Schema.String,
+    name: Schema.NullOr(Schema.String),
+    email: Schema.String,
+});
+// ── Query schemas (wire-level strings) ─────────────────────────────────────
+export const ErrorListQuery = Schema.Struct({
+    limit: Schema.optional(Schema.String),
+    offset: Schema.optional(Schema.String),
+    projectId: Schema.optional(Schema.String),
+    environmentId: Schema.optional(Schema.String),
+    severity: Schema.optional(Severity),
+    resolved: Schema.optional(Schema.String),
+    search: Schema.optional(Schema.String),
+});
+export const ErrorStatsQuery = Schema.Struct({
+    projectId: Schema.optional(Schema.String),
+    days: Schema.optional(Schema.String),
+});
+export const SourceMapsQuery = Schema.Struct({
+    limit: Schema.optional(Schema.String),
+    offset: Schema.optional(Schema.String),
+    release: Schema.optional(Schema.String),
+});
+export const ErrorWithProjectIdQuery = Schema.Struct({
+    projectId: Schema.String,
+});
+// ── Error list / detail ────────────────────────────────────────────────────
+export const ErrorListItem = Schema.Struct({
+    id: Schema.String,
+    app: Schema.NullOr(ProjectRef),
+    environment: Schema.NullOr(EnvironmentRef),
+    errorType: Schema.String,
+    message: Schema.String,
+    severity: Severity,
+    count: Schema.Number,
+    firstSeen: Schema.String,
+    lastSeen: Schema.String,
+    resolved: Schema.Boolean,
+    url: Schema.NullOr(Schema.String),
+});
+export const ListErrorsResult = Schema.Struct({
+    errors: Schema.Array(ErrorListItem),
+    total: Schema.Number,
+    limit: Schema.Number,
+    offset: Schema.Number,
+});
+export const ErrorDetail = Schema.Struct({
+    id: Schema.String,
+    app: Schema.NullOr(ProjectRef),
+    environment: Schema.NullOr(EnvironmentRef),
+    fingerprint: Schema.String,
+    errorType: Schema.String,
+    message: Schema.String,
+    stack: Schema.NullOr(Schema.String),
+    severity: Severity,
+    url: Schema.NullOr(Schema.String),
+    userAgent: Schema.NullOr(Schema.String),
+    userId: Schema.NullOr(Schema.String),
+    metadata: Schema.NullOr(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    count: Schema.Number,
+    firstSeen: Schema.String,
+    lastSeen: Schema.String,
+    resolved: Schema.Boolean,
+    resolvedAt: Schema.NullOr(Schema.String),
+    resolver: Schema.NullOr(ResolverRef),
+    createdAt: Schema.String,
+});
+export const GetErrorResult = ErrorDetail;
+export const ResolveErrorResult = Schema.Struct({ success: Schema.Boolean });
+export const DeleteErrorResult = Schema.Struct({ success: Schema.Boolean });
+// ── Stats ──────────────────────────────────────────────────────────────────
+export const RecentErrorSummary = Schema.Struct({
+    id: Schema.String,
+    errorType: Schema.String,
+    message: Schema.String,
+    count: Schema.Number,
+    lastSeen: Schema.String,
+});
+export const ErrorStatsResult = Schema.Struct({
+    total: Schema.Number,
+    unresolved: Schema.Number,
+    bySeverity: Schema.Record({ key: Schema.String, value: Schema.Number }),
+    recentErrors: Schema.Array(RecentErrorSummary),
+    period: Schema.String,
+});
+// ── Service Dashboard ──────────────────────────────────────────────────────
+export const ErrorByDay = Schema.Struct({
+    date: Schema.String,
+    count: Schema.Number,
+});
+export const ErrorBySeverityBreakdown = Schema.Struct({
+    severity: Schema.String,
+    count: Schema.Number,
+});
+export const RecentError = Schema.Struct({
+    id: Schema.String,
+    message: Schema.String,
+    severity: Schema.String,
+    occurrences: Schema.Number,
+    lastSeen: Schema.String,
+});
+export const GetMonitoringServiceDataResult = Schema.Struct({
+    app: ProjectRef,
+    errorsLast24h: Schema.Number,
+    errorsPrevious24h: Schema.Number,
+    unresolvedErrors: Schema.Number,
+    totalErrors: Schema.Number,
+    fatalErrorsThisWeek: Schema.Number,
+    errorsByDay: Schema.Array(ErrorByDay),
+    errorsBySeverity: Schema.Array(ErrorBySeverityBreakdown),
+    recentErrors: Schema.Array(RecentError),
+});
+// ── Source Maps ────────────────────────────────────────────────────────────
+export const SourceMapItem = Schema.Struct({
+    id: Schema.String,
+    release: Schema.String,
+    filename: Schema.String,
+    fileSize: Schema.NullOr(Schema.Number),
+    validated: Schema.Boolean,
+    uploadedAt: Schema.String,
+    expiresAt: Schema.NullOr(Schema.String),
+});
+export const ListSourceMapsResult = Schema.Struct({
+    maps: Schema.Array(SourceMapItem),
+    total: Schema.Number,
+    limit: Schema.Number,
+    offset: Schema.Number,
+});
+export const DeleteSourceMapsInput = Schema.Struct({
+    release: Schema.String,
+});
+export const DeleteSourceMapsResult = Schema.Struct({
+    deletedCount: Schema.Number,
+});
+// ── Stack Trace Resolution ─────────────────────────────────────────────────
+export const ResolvedStackFrame = Schema.Struct({
+    filename: Schema.optional(Schema.String),
+    function: Schema.optional(Schema.String),
+    lineno: Schema.optional(Schema.Number),
+    colno: Schema.optional(Schema.Number),
+    in_app: Schema.optional(Schema.Boolean),
+    originalFilename: Schema.optional(Schema.String),
+    originalLine: Schema.optional(Schema.Number),
+    originalColumn: Schema.optional(Schema.Number),
+    originalName: Schema.optional(Schema.String),
+    resolved: Schema.Boolean,
+});
+export const ResolveStackTraceResult = Schema.Struct({
+    resolved: Schema.Boolean,
+    reason: Schema.optional(Schema.String),
+    release: Schema.optional(Schema.String),
+    frames: Schema.Array(ResolvedStackFrame),
+});

package/dist/schemas/monitoring.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Monitoring — BaaS plane exception + message capture. Mirrors
+ * `@sylphx/sdk/monitoring.ts` (Sentry-style ingest envelope).
+ *
+ * Shape policy (ADR-084 Wave 2d): wire shapes match the Sentry /
+ * rrweb-adjacent envelope the SDK uses in production, not a bespoke flat
+ * form. This lets the server forward events directly to downstream
+ * Sentry-compatible ingest without a reshape pass.
+ */
+import { Schema } from 'effect';
+export declare const MonitoringSeverity: Schema.Literal<["fatal", "error", "warning", "info"]>;
+export type MonitoringSeverity = typeof MonitoringSeverity.Type;
+export declare const ExceptionFrame: Schema.Struct<{
+    filename: Schema.optional<typeof Schema.String>;
+    function: Schema.optional<typeof Schema.String>;
+    lineno: Schema.optional<typeof Schema.Number>;
+    colno: Schema.optional<typeof Schema.Number>;
+}>;
+export type ExceptionFrame = typeof ExceptionFrame.Type;
+export declare const ExceptionValue: Schema.Struct<{
+    type: typeof Schema.String;
+    value: typeof Schema.String;
+    stacktrace: Schema.optional<Schema.Struct<{
+        frames: Schema.Array$<Schema.Struct<{
+            filename: Schema.optional<typeof Schema.String>;
+            function: Schema.optional<typeof Schema.String>;
+            lineno: Schema.optional<typeof Schema.Number>;
+            colno: Schema.optional<typeof Schema.Number>;
+        }>>;
+    }>>;
+}>;
+export type ExceptionValue = typeof ExceptionValue.Type;
+/**
+ * Sentry-style exception envelope. `values` is an ordered list where the
+ * first entry is the primary exception and subsequent entries are its
+ * chained causes (innermost cause last). Wire-compatible with Sentry SDK
+ * v7/v8.
+ */
+export declare const ExceptionEnvelope: Schema.Struct<{
+    values: Schema.Array$<Schema.Struct<{
+        type: typeof Schema.String;
+        value: typeof Schema.String;
+        stacktrace: Schema.optional<Schema.Struct<{
+            frames: Schema.Array$<Schema.Struct<{
+                filename: Schema.optional<typeof Schema.String>;
+                function: Schema.optional<typeof Schema.String>;
+                lineno: Schema.optional<typeof Schema.Number>;
+                colno: Schema.optional<typeof Schema.Number>;
+            }>>;
+        }>>;
+    }>>;
+}>;
+export type ExceptionEnvelope = typeof ExceptionEnvelope.Type;
+/**
+ * Breadcrumb — contextual event preceding an exception. Matches Sentry
+ * breadcrumb shape (`ui.click`, `navigation`, `http`, ...).
+ */
+export declare const Breadcrumb: Schema.Struct<{
+    type: Schema.optional<typeof Schema.String>;
+    level: Schema.optional<Schema.Literal<["fatal", "error", "warning", "info"]>>;
+    message: Schema.optional<typeof Schema.String>;
+    data: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    /** Unix timestamp in seconds (Sentry convention). */
+    timestamp: Schema.optional<typeof Schema.Number>;
+}>;
+export type Breadcrumb = typeof Breadcrumb.Type;
+export declare const CaptureExceptionInput: Schema.Struct<{
+    /**
+     * Sentry-style envelope. The legacy single-`ExceptionValue` form is
+     * represented as `{ values: [single] }`.
+     */
+    exception: Schema.Struct<{
+        values: Schema.Array$<Schema.Struct<{
+            type: typeof Schema.String;
+            value: typeof Schema.String;
+            stacktrace: Schema.optional<Schema.Struct<{
+                frames: Schema.Array$<Schema.Struct<{
+                    filename: Schema.optional<typeof Schema.String>;
+                    function: Schema.optional<typeof Schema.String>;
+                    lineno: Schema.optional<typeof Schema.Number>;
+                    colno: Schema.optional<typeof Schema.Number>;
+                }>>;
+            }>>;
+        }>>;
+    }>;
+    level: Schema.optional<Schema.Literal<["fatal", "error", "warning", "info"]>>;
+    route: Schema.optional<typeof Schema.String>;
+    userAgent: Schema.optional<typeof Schema.String>;
+    release: Schema.optional<typeof Schema.String>;
+    environment: Schema.optional<typeof Schema.String>;
+    tags: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    extra: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    breadcrumbs: Schema.optional<Schema.Array$<Schema.Struct<{
+        type: Schema.optional<typeof Schema.String>;
+        level: Schema.optional<Schema.Literal<["fatal", "error", "warning", "info"]>>;
+        message: Schema.optional<typeof Schema.String>;
+        data: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        /** Unix timestamp in seconds (Sentry convention). */
+        timestamp: Schema.optional<typeof Schema.Number>;
+    }>>>;
+    fingerprint: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    userId: Schema.optional<typeof Schema.String>;
+    timestamp: Schema.optional<typeof Schema.String>;
+}>;
+export type CaptureExceptionInput = typeof CaptureExceptionInput.Type;
+export declare const CaptureMessageInput: Schema.Struct<{
+    message: typeof Schema.String;
+    level: Schema.optional<Schema.Literal<["fatal", "error", "warning", "info"]>>;
+    route: Schema.optional<typeof Schema.String>;
+    release: Schema.optional<typeof Schema.String>;
+    tags: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    extra: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    userId: Schema.optional<typeof Schema.String>;
+    timestamp: Schema.optional<typeof Schema.String>;
+}>;
+export type CaptureMessageInput = typeof CaptureMessageInput.Type;
+/**
+ * Rich monitoring response. Superset of the legacy flat
+ * `{ eventId, sampled }` and the SDK's `MonitoringResponse`
+ * (`{ eventId, isNewError, quotaUsage?, recommendedSampleRate? }`).
+ *
+ * - `eventId` is always present.
+ * - Either `sampled` (legacy) or `isNewError` (SDK) will be present
+ *   depending on server version. Clients should not require both.
+ * - `quotaUsage` / `recommendedSampleRate` are emitted by newer servers
+ *   when quota usage >= 50% to let the SDK adaptively downsample.
+ */
+export declare const CaptureResult: Schema.Struct<{
+    eventId: typeof Schema.String;
+    /** Legacy flag — true if the event was retained after sampling. */
+    sampled: Schema.optional<typeof Schema.Boolean>;
+    /** True if this is a new unique error (billed), false if duplicate (free). */
+    isNewError: Schema.optional<typeof Schema.Boolean>;
+    /** Current quota usage percentage (0-100+). Emitted when >= 50%. */
+    quotaUsage: Schema.optional<typeof Schema.Number>;
+    /**
+     * Recommended client sample rate (0.0-1.0). Emitted alongside
+     * `quotaUsage`. Clients should downsample to this value when set.
+     */
+    recommendedSampleRate: Schema.optional<typeof Schema.Number>;
+}>;
+export type CaptureResult = typeof CaptureResult.Type;
+//# sourceMappingURL=monitoring.d.ts.map

package/dist/schemas/monitoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitoring.d.ts","sourceRoot":"","sources":["../../src/schemas/monitoring.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,eAAO,MAAM,kBAAkB,uDAAsD,CAAA;AACrF,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D,eAAO,MAAM,cAAc;;;;;EAKzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,eAAO,MAAM,cAAc;;;;;;;;;;;EAIzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;EAE5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;IAKtB,qDAAqD;;EAEpD,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAE/C,eAAO,MAAM,qBAAqB;IACjC;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;QATH,qDAAqD;;;;;;EAsBpD,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE,eAAO,MAAM,mBAAmB;;;;;;;;;EAS9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa;;IAEzB,mEAAmE;;IAEnE,8EAA8E;;IAE9E,oEAAoE;;IAEpE;;;OAGG;;EAEF,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA"}

package/dist/schemas/monitoring.js

@@ -0,0 +1,96 @@
+/**
+ * Monitoring — BaaS plane exception + message capture. Mirrors
+ * `@sylphx/sdk/monitoring.ts` (Sentry-style ingest envelope).
+ *
+ * Shape policy (ADR-084 Wave 2d): wire shapes match the Sentry /
+ * rrweb-adjacent envelope the SDK uses in production, not a bespoke flat
+ * form. This lets the server forward events directly to downstream
+ * Sentry-compatible ingest without a reshape pass.
+ */
+import { Schema } from 'effect';
+export const MonitoringSeverity = Schema.Literal('fatal', 'error', 'warning', 'info');
+export const ExceptionFrame = Schema.Struct({
+    filename: Schema.optional(Schema.String),
+    function: Schema.optional(Schema.String),
+    lineno: Schema.optional(Schema.Number),
+    colno: Schema.optional(Schema.Number),
+});
+export const ExceptionValue = Schema.Struct({
+    type: Schema.String,
+    value: Schema.String,
+    stacktrace: Schema.optional(Schema.Struct({ frames: Schema.Array(ExceptionFrame) })),
+});
+/**
+ * Sentry-style exception envelope. `values` is an ordered list where the
+ * first entry is the primary exception and subsequent entries are its
+ * chained causes (innermost cause last). Wire-compatible with Sentry SDK
+ * v7/v8.
+ */
+export const ExceptionEnvelope = Schema.Struct({
+    values: Schema.Array(ExceptionValue),
+});
+/**
+ * Breadcrumb — contextual event preceding an exception. Matches Sentry
+ * breadcrumb shape (`ui.click`, `navigation`, `http`, ...).
+ */
+export const Breadcrumb = Schema.Struct({
+    type: Schema.optional(Schema.String),
+    level: Schema.optional(MonitoringSeverity),
+    message: Schema.optional(Schema.String),
+    data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    /** Unix timestamp in seconds (Sentry convention). */
+    timestamp: Schema.optional(Schema.Number),
+});
+export const CaptureExceptionInput = Schema.Struct({
+    /**
+     * Sentry-style envelope. The legacy single-`ExceptionValue` form is
+     * represented as `{ values: [single] }`.
+     */
+    exception: ExceptionEnvelope,
+    level: Schema.optional(MonitoringSeverity),
+    route: Schema.optional(Schema.String),
+    userAgent: Schema.optional(Schema.String),
+    release: Schema.optional(Schema.String),
+    environment: Schema.optional(Schema.String),
+    tags: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+    extra: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    breadcrumbs: Schema.optional(Schema.Array(Breadcrumb)),
+    fingerprint: Schema.optional(Schema.Array(Schema.String)),
+    userId: Schema.optional(Schema.String),
+    timestamp: Schema.optional(Schema.String),
+});
+export const CaptureMessageInput = Schema.Struct({
+    message: Schema.String,
+    level: Schema.optional(MonitoringSeverity),
+    route: Schema.optional(Schema.String),
+    release: Schema.optional(Schema.String),
+    tags: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+    extra: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    userId: Schema.optional(Schema.String),
+    timestamp: Schema.optional(Schema.String),
+});
+/**
+ * Rich monitoring response. Superset of the legacy flat
+ * `{ eventId, sampled }` and the SDK's `MonitoringResponse`
+ * (`{ eventId, isNewError, quotaUsage?, recommendedSampleRate? }`).
+ *
+ * - `eventId` is always present.
+ * - Either `sampled` (legacy) or `isNewError` (SDK) will be present
+ *   depending on server version. Clients should not require both.
+ * - `quotaUsage` / `recommendedSampleRate` are emitted by newer servers
+ *   when quota usage >= 50% to let the SDK adaptively downsample.
+ */
+export const CaptureResult = Schema.Struct({
+    eventId: Schema.String,
+    /** Legacy flag — true if the event was retained after sampling. */
+    sampled: Schema.optional(Schema.Boolean),
+    /** True if this is a new unique error (billed), false if duplicate (free). */
+    isNewError: Schema.optional(Schema.Boolean),
+    /** Current quota usage percentage (0-100+). Emitted when >= 50%. */
+    quotaUsage: Schema.optional(Schema.Number),
+    /**
+     * Recommended client sample rate (0.0-1.0). Emitted alongside
+     * `quotaUsage`. Clients should downsample to this value when set.
+     */
+    recommendedSampleRate: Schema.optional(Schema.Number),
+});