@sincpro/client-framework 0.1.0 → 0.2.0

package/AGENTS.md

@@ -16,15 +16,16 @@ it says what this package is responsible for and what it is not. This file is ho
 
 ## Where things go
 
-| Folder               | What                                                                                    |
-| -------------------- | --------------------------------------------------------------------------------------- |
-| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract, ids |
-| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones            |
-| `src/services/`      | `Feature`, `ApplicationService`, the runtime, the execution and what binds to it        |
-| `src/observability/` | The ports a platform plugs: `Tracer`, `ErrorReporter`                                   |
-| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed  |
-| `src/testing/`       | `memoryTracer`, `memoryReporter` — the ports in memory, for tests                       |
-| `tests/`             | vitest in Node; `tests/support/` holds the fake domains and forge's real contracts      |
+| Folder               | What                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| `src/client/`        | The seam with a server: `Transport`, REST, memory, `entity()`, the client contract, ids     |
+| `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones                |
+| `src/services/`      | `Feature`, `ApplicationService`, the runtime, the execution and what binds to it            |
+| `src/observability/` | The ports a platform plugs: `Tracer`, `ErrorReporter`                                       |
+| `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed      |
+| `src/adapters/`      | Optional entries over a vendor (`./opentelemetry`, `./sentry`): the only place one is named |
+| `src/testing/`       | `memoryTracer`, `memoryReporter` — the ports in memory, for tests                           |
+| `tests/`             | vitest in Node; `tests/support/` holds the fake domains and forge's real contracts          |
 
 ## Hard rules (the build enforces them — `make doctor`)
 
@@ -62,6 +63,12 @@ it says what this package is responsible for and what it is not. This file is ho
   and read the diff.
 - **A module name the generator writes is built in parts** (`codegen/names.ts`, `FRAMEWORK`): the
   build's `tsc-alias` rewrites this package's specifiers inside strings too.
+- **An adapter wraps what the application built, never builds it.** `openTelemetryTracer` takes
+  the app's tracer, `sentryReporter` the app's client: no `register()`, no `Sentry.init()`, no
+  endpoint or DSN here, nothing read from the environment. A vendor's SDK is imported only in
+  `src/adapters/`, and nothing else imports an adapter (`make doctor`).
+- **A span nothing records claims no trace.** OpenTelemetry's API with no provider answers an
+  all-zeros span: the adapter gives no ids, so no `traceparent` of zeros reaches the server.
 - **Reported means unexpected.** A `TransportError` the server answered with a 4xx is `refused`,
   an `AbortError` is `aborted`; neither is reported (`outcomeOf`). Change that with
   `RuntimeOptions.outcomeOf`, never by catching in a Feature.

package/MANIFESTO.md

@@ -58,8 +58,11 @@ server-side render, in a script and in a test, unchanged.**
   with the libraries that do it best.
 - **Not offline storage.** SQLite on a phone or IndexedDB in a point of sale are platform
   adapters.
-- **Not a telemetry or error-tracking SDK.** It defines the ports and calls them; it bundles no
-  vendor.
+- **Not a telemetry or error-tracking SDK.** It defines the ports and calls them. For the
+  common vendors it offers optional adapters (`./opentelemetry`, `./sentry`) that wrap what the
+  application built — its provider, its client, with its endpoint and its DSN. It initialises
+  nothing and registers nothing global; an application that does not import them installs
+  nothing and ships nothing, and without a tracer or a reporter everything runs the same.
 - **Not where business rules live.** The server keeps them; a client reads what it publishes.
 - **Not an event bus**, and not a dispatcher: a use case is executed by calling it, and the
   interceptors are what make that call traced and reported.

package/README.md

@@ -43,9 +43,21 @@ const project = bindServices(runtime, "project", {
 await project.closeIssue.execute(input); // project/closeIssue → project/preview, project/send
 ```
 
-`tracer` and `reporter` are the platform's: OpenTelemetry and GlitchTip in a browser, a queue on
-a phone, `memoryTracer()` and `memoryReporter()` (`@sincpro/client-framework/testing`) in a test.
-A use case that was never bound runs too, with nothing tracing.
+`tracer` and `reporter` are injected by the application — this package initialises nothing.
+Any object that fulfils the port works; for the common vendors there are optional adapters that
+wrap what the application built:
+
+```ts
+import { openTelemetryTracer } from "@sincpro/client-framework/opentelemetry"; // peer: @opentelemetry/api
+import { sentryReporter } from "@sincpro/client-framework/sentry"; // no dependency
+
+const tracer = openTelemetryTracer(provider.getTracer("my-app")); // the app's provider and exporter
+const reporter = sentryReporter(client); // the app's Sentry-compatible client (GlitchTip too)
+```
+
+Nothing is installed or shipped unless it is imported, and without a tracer or a reporter every use
+case runs the same — nothing traces, nothing reports. In a test, `memoryTracer()` and
+`memoryReporter()` (`@sincpro/client-framework/testing`).
 
 ## Where it sits
 

package/dist/adapters/opentelemetry.d.ts

@@ -0,0 +1,21 @@
+import { type Tracer as OtelTracer } from "@opentelemetry/api";
+import type { Tracer } from "../observability/ports.js";
+/**
+ * The `Tracer` port over OpenTelemetry's API: every use case a span of whatever provider the
+ * platform registered.
+ *
+ *     // a browser (@sincpro/web-framework/telemetry does this), Node, React Native…
+ *     const tracer = openTelemetryTracer(provider.getTracer("forge-web"));
+ *     const runtime = createRuntime({ tracer });
+ *
+ * Context: only `@opentelemetry/api`, which runs the same on every platform — the provider, its
+ * exporter and where it sends are the platform's (the browser's OTLP over fetch, a phone's
+ * queue, a server's SDK). An optional entry with an optional peer: an application that does not
+ * import it installs nothing and ships nothing.
+ *
+ * The parent is given, never read from OpenTelemetry's context: a run carries its own execution
+ * (`Execution`), so two use cases at once never take each other's span, and no context manager
+ * (Zone.js) is needed. A span nothing records (a sampler said no, no provider registered)
+ * answers no ids — so no `traceparent` claims a trace that does not exist.
+ */
+export declare function openTelemetryTracer(tracer: OtelTracer): Tracer;

package/dist/adapters/opentelemetry.js

@@ -0,0 +1,68 @@
+import { isSpanContextValid, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, TraceFlags, } from "@opentelemetry/api";
+/**
+ * The `Tracer` port over OpenTelemetry's API: every use case a span of whatever provider the
+ * platform registered.
+ *
+ *     // a browser (@sincpro/web-framework/telemetry does this), Node, React Native…
+ *     const tracer = openTelemetryTracer(provider.getTracer("forge-web"));
+ *     const runtime = createRuntime({ tracer });
+ *
+ * Context: only `@opentelemetry/api`, which runs the same on every platform — the provider, its
+ * exporter and where it sends are the platform's (the browser's OTLP over fetch, a phone's
+ * queue, a server's SDK). An optional entry with an optional peer: an application that does not
+ * import it installs nothing and ships nothing.
+ *
+ * The parent is given, never read from OpenTelemetry's context: a run carries its own execution
+ * (`Execution`), so two use cases at once never take each other's span, and no context manager
+ * (Zone.js) is needed. A span nothing records (a sampler said no, no provider registered)
+ * answers no ids — so no `traceparent` claims a trace that does not exist.
+ */
+export function openTelemetryTracer(tracer) {
+    return {
+        start(name, options) {
+            const parent = options.parent;
+            const parentContext = parent !== undefined && parent.traceId !== "" && parent.spanId !== ""
+                ? trace.setSpanContext(ROOT_CONTEXT, {
+                    traceId: parent.traceId,
+                    spanId: parent.spanId,
+                    traceFlags: parent.sampled ? TraceFlags.SAMPLED : TraceFlags.NONE,
+                    isRemote: false,
+                })
+                : ROOT_CONTEXT;
+            const span = tracer.startSpan(name, {
+                kind: SpanKind.INTERNAL,
+                ...(options.attributes ? { attributes: options.attributes } : {}),
+            }, parentContext);
+            const own = span.spanContext();
+            const valid = isSpanContextValid(own);
+            const state = own.traceState?.serialize();
+            return {
+                traceId: valid ? own.traceId : "",
+                spanId: valid ? own.spanId : "",
+                sampled: valid && (own.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED,
+                ...(state ? { state } : {}),
+                set: (attributes) => void span.setAttributes(attributes),
+                end: (outcome, error) => close(span, outcome, error),
+            };
+        },
+    };
+}
+/**
+ * How the use case ended, said the way OpenTelemetry reads it: `failed` is an error with its
+ * exception; `refused` and `aborted` are expected answers — said in `sincpro.outcome`, never as
+ * an error, the way the backend leaves a refusal out of its error rate.
+ */
+function close(span, outcome, error) {
+    span.setAttribute("sincpro.outcome", outcome);
+    if (outcome === "failed") {
+        if (error instanceof Error)
+            span.recordException(error);
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            ...(error instanceof Error ? { message: error.message } : {}),
+        });
+    }
+    else if (outcome === "ok")
+        span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+}

package/dist/adapters/sentry.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorReporter } from "../observability/ports.js";
+/**
+ * What this adapter needs of a Sentry-compatible client: its `captureException`. A browser's
+ * `BrowserClient`, Node's, React Native's — and GlitchTip, which speaks Sentry's protocol.
+ */
+export type ExceptionClient = {
+    captureException(error: unknown, hint?: {
+        captureContext?: {
+            tags?: Record<string, string>;
+            contexts?: Record<string, Record<string, unknown>>;
+        };
+    }): unknown;
+};
+/**
+ * The `ErrorReporter` port over a Sentry-compatible client: an unexpected error reported with the
+ * use case it happened in, its trace — the id the backend logged too — and its context.
+ *
+ *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
+ *     const reporter = sentryReporter(client);
+ *     const runtime = createRuntime({ reporter });
+ *
+ * Context: it imports nothing — it takes the client the platform made (with its DSN, release
+ * and data rules), so it costs no dependency and works on every platform. What is reported is
+ * already decided by the runtime (`outcomeOf`: only `failed`); this only says where it happened.
+ * The context goes as a context, not as tags: a tag is indexed and searched, and an execution's
+ * values are not the place for that.
+ */
+export declare function sentryReporter(client: ExceptionClient): ErrorReporter;

package/dist/adapters/sentry.js

@@ -0,0 +1,36 @@
+/**
+ * The `ErrorReporter` port over a Sentry-compatible client: an unexpected error reported with the
+ * use case it happened in, its trace — the id the backend logged too — and its context.
+ *
+ *     // @sincpro/web-framework/errors builds the browser's client with GlitchTip's DSN
+ *     const reporter = sentryReporter(client);
+ *     const runtime = createRuntime({ reporter });
+ *
+ * Context: it imports nothing — it takes the client the platform made (with its DSN, release
+ * and data rules), so it costs no dependency and works on every platform. What is reported is
+ * already decided by the runtime (`outcomeOf`: only `failed`); this only says where it happened.
+ * The context goes as a context, not as tags: a tag is indexed and searched, and an execution's
+ * values are not the place for that.
+ */
+export function sentryReporter(client) {
+    return {
+        report(error, about) {
+            client.captureException(error, {
+                captureContext: {
+                    tags: {
+                        "sincpro.use_case": about.useCase,
+                        ...(about.traceId === "" ? {} : { trace_id: about.traceId }),
+                    },
+                    contexts: {
+                        sincpro: {
+                            use_case: about.useCase,
+                            execution_id: about.executionId,
+                            ...(about.traceId === "" ? {} : { trace_id: about.traceId }),
+                            context: about.context,
+                        },
+                    },
+                },
+            });
+        },
+    };
+}

package/dist/services/feature.js

@@ -114,6 +114,20 @@ function intercepted(target, binding) {
     TARGETS.set(proxy, target);
     return proxy;
 }
+/**
+ * Whether this is the first run to report this error. A Feature that fails inside an
+ * ApplicationService throws through it: the error is reported once, by the run where it
+ * happened — its span is the one that says where — and every run around it still ends `failed`.
+ */
+const REPORTED = new WeakSet();
+function firstReport(error) {
+    if (error === null || (typeof error !== "object" && typeof error !== "function"))
+        return true;
+    if (REPORTED.has(error))
+        return false;
+    REPORTED.add(error);
+    return true;
+}
 function quietly(work, otherwise) {
     try {
         return work();
@@ -177,7 +191,7 @@ function run(target, method, body, args, binding) {
     const finish = (failed, error) => {
         const outcome = failed ? quietly(() => runtime.outcomeOf(error), "failed") : "ok";
         quietly(() => span.end(outcome, error), undefined);
-        if (outcome === "failed")
+        if (outcome === "failed" && firstReport(error))
             quietly(() => runtime.reporter?.report(error, {
                 useCase,
                 traceId: span.traceId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sincpro/client-framework",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The client side of sincpro_framework, for every platform: Feature and ApplicationService traced and reported by default, applications made of domains, and the typed client generated from a service's contract. No React, no DOM.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,14 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
+    },
+    "./opentelemetry": {
+      "types": "./dist/adapters/opentelemetry.d.ts",
+      "default": "./dist/adapters/opentelemetry.js"
+    },
+    "./sentry": {
+      "types": "./dist/adapters/sentry.d.ts",
+      "default": "./dist/adapters/sentry.js"
     }
   },
   "bin": {
@@ -59,11 +67,19 @@
     "printWidth": 94
   },
   "peerDependencies": {
-    "@sincpro/criteria": "^1.1.0"
+    "@opentelemetry/api": "^1.10.0",
+    "@sincpro/criteria": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@sincpro/criteria": "^1.1.0",
+    "@opentelemetry/api": "1.10.0",
+    "@opentelemetry/sdk-trace": "3.1.0",
+    "@sincpro/criteria": "^2.0.0",
     "@types/node": "^26.6.6",
     "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",