crumbtrail-install-shared 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crumbtrail
+
+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/dist/index.cjs

@@ -0,0 +1,227 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BACKEND_JS_STACKS: () => BACKEND_JS_STACKS,
+  INFRA_STACKS: () => INFRA_STACKS,
+  JS_STACKS: () => JS_STACKS,
+  OTLP_CAPABILITY_FACTS: () => OTLP_CAPABILITY_FACTS,
+  OTLP_STACKS: () => OTLP_STACKS,
+  allStackInstalls: () => allStackInstalls,
+  buildAgentPrompt: () => buildAgentPrompt,
+  buildBackendJsNote: () => buildBackendJsNote,
+  buildOtlpSnippets: () => buildOtlpSnippets,
+  getInstallVariant: () => getInstallVariant,
+  otlpAuthHeaderValue: () => otlpAuthHeaderValue,
+  otlpBearerHeaderValue: () => otlpBearerHeaderValue
+});
+module.exports = __toCommonJS(index_exports);
+var import_crumbtrail_core = require("crumbtrail-core");
+var JS_STACKS = [
+  "nextjs",
+  "react",
+  "vue",
+  "svelte",
+  "vite",
+  "express",
+  "hono",
+  "node"
+];
+var BACKEND_JS_STACKS = ["express", "hono", "node"];
+var OTLP_STACKS = [
+  "django",
+  "flask",
+  "fastapi",
+  "dotnet",
+  "go",
+  "rails"
+];
+var INFRA_STACKS = [
+  "postgres",
+  "grafana",
+  "loki",
+  "docker"
+];
+function getInstallVariant(stack) {
+  const backendJs = BACKEND_JS_STACKS.includes(stack);
+  if (JS_STACKS.includes(stack)) {
+    return { stack, kind: "js", backendJs, comingSoon: false };
+  }
+  if (OTLP_STACKS.includes(stack)) {
+    return { stack, kind: "otlp", backendJs: false, comingSoon: false };
+  }
+  return { stack, kind: "infra", backendJs: false, comingSoon: true };
+}
+function allStackInstalls() {
+  return import_crumbtrail_core.STACK_IDS.map(getInstallVariant);
+}
+function buildBackendJsNote(stack) {
+  if (stack === "express") {
+    return [
+      "// Backend (Express) \u2014 also capture server-side errors and requests.",
+      "// Reuse the same ingest endpoint + key you set on the SDK above.",
+      "import {",
+      "  createCrumbtrailExpressMiddleware,",
+      "  createCrumbtrailExpressErrorMiddleware,",
+      '} from "crumbtrail-node";',
+      "",
+      "const crumbtrailOptions = { endpoint: CRUMBTRAIL_ENDPOINT, authToken: CRUMBTRAIL_KEY };",
+      "app.use(createCrumbtrailExpressMiddleware(crumbtrailOptions));      // before your routes",
+      "app.use(createCrumbtrailExpressErrorMiddleware(crumbtrailOptions)); // after your routes",
+      "",
+      "// Prefer OpenTelemetry? Point your OTLP exporter at the receiver instead."
+    ].join("\n");
+  }
+  return [
+    "// Backend (Hono / Node) \u2014 crumbtrail-node ships no framework middleware here.",
+    "// Open a headless session and record server-side events against it:",
+    'import { startHeadlessSession } from "crumbtrail-node";',
+    "",
+    "const session = await startHeadlessSession({",
+    "  endpoint: CRUMBTRAIL_ENDPOINT,",
+    "  authToken: CRUMBTRAIL_KEY,",
+    '  sessionId: "<your-session-id>",',
+    "});",
+    "// session.record(event) to attach server events; session.end() when done.",
+    "",
+    "// Prefer OpenTelemetry? Point your OTLP exporter at the receiver instead."
+  ].join("\n");
+}
+var OTLP_CAPABILITY_FACTS = {
+  paths: ["/v1/traces", "/v1/logs"],
+  protocols: ["http/protobuf", "http/json"],
+  authHeaders: ["X-Crumbtrail-Auth", "Authorization: Bearer"],
+  compression: { recommended: "none", accepted: ["none", "gzip"] },
+  sessionAttribute: "crumbtrail.session.id"
+};
+function otlpAuthHeaderValue(apiKey) {
+  return `X-Crumbtrail-Auth=${apiKey}`;
+}
+function otlpBearerHeaderValue(apiKey) {
+  return `Authorization=Bearer%20${apiKey}`;
+}
+function buildOtlpSnippets({
+  endpoint,
+  apiKey
+}) {
+  const [protobuf, jsonProtocol] = OTLP_CAPABILITY_FACTS.protocols;
+  return {
+    env: [
+      `OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint}`,
+      `OTEL_EXPORTER_OTLP_PROTOCOL=${protobuf}   # or ${jsonProtocol}`,
+      `OTEL_EXPORTER_OTLP_COMPRESSION=${OTLP_CAPABILITY_FACTS.compression.recommended}   # recommended; gzip is also accepted`
+    ].join("\n"),
+    authHeader: [
+      `OTEL_EXPORTER_OTLP_HEADERS=${otlpAuthHeaderValue(apiKey)}`,
+      `# Or, if your exporter sends a Bearer token (note the %20-escaped space):`,
+      `# OTEL_EXPORTER_OTLP_HEADERS=${otlpBearerHeaderValue(apiKey)}`
+    ].join("\n"),
+    sessionAttr: `OTEL_RESOURCE_ATTRIBUTES=${OTLP_CAPABILITY_FACTS.sessionAttribute}=<your-session-id>`,
+    note: `Crumbtrail's OTLP receiver appends ${OTLP_CAPABILITY_FACTS.paths.join(" and ")} to the endpoint above \u2014 don't include those paths yourself. Set the ${OTLP_CAPABILITY_FACTS.sessionAttribute} resource attribute to join backend spans to the frontend session.`
+  };
+}
+function buildAgentPrompt(stack, keys) {
+  const { kind, backendJs } = getInstallVariant(stack);
+  const { endpoint, apiKey } = keys;
+  const header = [
+    "You are setting up Crumbtrail in this project. Make ONLY the changes below,",
+    "do not refactor or touch anything else, then verify the build still passes.",
+    "",
+    `Ingest endpoint: ${endpoint}`,
+    `Ingest key:      ${apiKey}`,
+    ""
+  ];
+  if (kind === "otlp") {
+    return [
+      ...header,
+      "This is a non-JS backend that already uses OpenTelemetry. Do NOT install a",
+      "second SDK. Instead, add Crumbtrail as an additional OTLP/HTTP exporter:",
+      `  1. Set OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint} (the exporter appends`,
+      "     /v1/traces and /v1/logs \u2014 do not add those paths).",
+      `  2. Send the auth header X-Crumbtrail-Auth: ${apiKey} on every export`,
+      "     (or Authorization: Bearer <key> if your exporter prefers that).",
+      "  3. Stamp the resource attribute crumbtrail.session.id so spans/logs join",
+      "     the right session.",
+      "  4. Keep your existing exporter \u2014 add Crumbtrail alongside it.",
+      "  5. Verify the app still builds and starts."
+    ].join("\n");
+  }
+  const jsLines = [
+    ...header,
+    "This is a JavaScript/TypeScript project. Do the following:",
+    "  1. Install the SDK:  npm install crumbtrail-core",
+    '  2. Import the SDK:  import { Crumbtrail, PRESET_PASSIVE } from "crumbtrail-core";',
+    "  3. Initialize once at the app entry point with PRESET_PASSIVE:",
+    "       Crumbtrail.init({",
+    "         ...PRESET_PASSIVE,",
+    `         httpEndpoint: "${endpoint}",`,
+    `         httpAuthToken: "${apiKey}",`,
+    "       });"
+  ];
+  if (backendJs && stack === "express") {
+    jsLines.push(
+      "  4. This is an Express backend \u2014 also install crumbtrail-node and capture",
+      "     server errors and requests with its Express middleware:",
+      "       import {",
+      "         createCrumbtrailExpressMiddleware,",
+      "         createCrumbtrailExpressErrorMiddleware,",
+      '       } from "crumbtrail-node";',
+      `       const opts = { endpoint: "${endpoint}", authToken: "${apiKey}" };`,
+      "       app.use(createCrumbtrailExpressMiddleware(opts));      // before your routes",
+      "       app.use(createCrumbtrailExpressErrorMiddleware(opts)); // after your routes",
+      "  5. Change nothing else, then verify the build still passes."
+    );
+  } else if (backendJs) {
+    jsLines.push(
+      "  4. This is also a backend. Install crumbtrail-node; it ships no framework",
+      "     middleware for this stack, so open a headless session and record",
+      "     server-side events against it:",
+      '       import { startHeadlessSession } from "crumbtrail-node";',
+      "       const session = await startHeadlessSession({",
+      `         endpoint: "${endpoint}",`,
+      `         authToken: "${apiKey}",`,
+      '         sessionId: "<your-session-id>",',
+      "       });",
+      "       // session.record(event) for server events; session.end() when the request ends.",
+      "  5. Change nothing else, then verify the build still passes."
+    );
+  } else {
+    jsLines.push(
+      "  4. Change nothing else, then verify the build still passes."
+    );
+  }
+  return jsLines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BACKEND_JS_STACKS,
+  INFRA_STACKS,
+  JS_STACKS,
+  OTLP_CAPABILITY_FACTS,
+  OTLP_STACKS,
+  allStackInstalls,
+  buildAgentPrompt,
+  buildBackendJsNote,
+  buildOtlpSnippets,
+  getInstallVariant,
+  otlpAuthHeaderValue,
+  otlpBearerHeaderValue
+});

package/dist/index.d.cts

@@ -0,0 +1,109 @@
+import { Stack } from 'crumbtrail-core';
+
+type InstallVariantKind = "js" | "otlp" | "infra";
+/** JS/TS stacks that install crumbtrail-core directly. */
+declare const JS_STACKS: readonly Stack[];
+/** JS backends that additionally wire the crumbtrail-node middleware. */
+declare const BACKEND_JS_STACKS: readonly Stack[];
+/** Non-JS backends wired via their existing OpenTelemetry exporter. */
+declare const OTLP_STACKS: readonly Stack[];
+/** Evidence sources that are not yet a first-class ingest target. */
+declare const INFRA_STACKS: readonly Stack[];
+interface StackInstall {
+    stack: Stack;
+    kind: InstallVariantKind;
+    /** True for express/hono/node — they also need the backend middleware note. */
+    backendJs: boolean;
+    /** True for infra evidence sources — surfaced as "coming soon". */
+    comingSoon: boolean;
+}
+/** Classify a single stack into its install variant. Total over all 18 stacks. */
+declare function getInstallVariant(stack: Stack): StackInstall;
+/** The classification table for every supported stack (handy for tests/UI). */
+declare function allStackInstalls(): StackInstall[];
+interface EndpointKey {
+    /** Live ingest endpoint (the cloud origin / dashboard origin). */
+    endpoint: string;
+    /** Live ingest key used as the auth token. */
+    apiKey: string;
+}
+/**
+ * The crumbtrail-node backend note shown under <InstallSteps/> for the backend-JS
+ * stacks. Uses ONLY the real crumbtrail-node exports — no invented names:
+ *   • Express is the only stack with framework middleware
+ *     (createCrumbtrailExpressMiddleware / createCrumbtrailExpressErrorMiddleware).
+ *   • Hono / Node ship no framework middleware, so they open a headless session
+ *     (startHeadlessSession) and record server-side events against it.
+ */
+declare function buildBackendJsNote(stack: Stack): string;
+/**
+ * Single source of truth for what Crumbtrail's OTLP/HTTP receiver accepts. Both
+ * `buildOtlpSnippets` (the wizard guidance) and the collector recipes in
+ * `packages/node/src/provider-recipes.json` must agree with these facts — a
+ * consistency test asserts the two never drift (compression, endpoint path
+ * suffix, auth header names).
+ *
+ * Nothing here is invented: the paths, protocols, auth headers, and session
+ * attribute all match the live ingest routes served by packages/node/src/server.ts
+ * and by the hosted Crumbtrail cloud.
+ */
+interface OtlpCapabilityFacts {
+    /** Signal paths the receiver serves; exporters append these to the endpoint. */
+    readonly paths: readonly ["/v1/traces", "/v1/logs"];
+    /** OTLP/HTTP wire protocols accepted (both, as of the protobuf+gzip parity CP). */
+    readonly protocols: readonly ["http/protobuf", "http/json"];
+    /** Auth header names honored equivalently by the receiver. */
+    readonly authHeaders: readonly ["X-Crumbtrail-Auth", "Authorization: Bearer"];
+    /** Content-Encoding posture: "none" recommended for collectors; gzip accepted. */
+    readonly compression: {
+        readonly recommended: "none";
+        readonly accepted: readonly ["none", "gzip"];
+    };
+    /** Resource/span attribute that files spans/logs into a Crumbtrail session. */
+    readonly sessionAttribute: "crumbtrail.session.id";
+}
+declare const OTLP_CAPABILITY_FACTS: OtlpCapabilityFacts;
+/**
+ * The `X-Crumbtrail-Auth=<key>` value for `OTEL_EXPORTER_OTLP_HEADERS`.
+ * OTEL parses that env var as comma-separated `name=value` pairs; the value is
+ * used verbatim, so a plain key needs no escaping here.
+ */
+declare function otlpAuthHeaderValue(apiKey: string): string;
+/**
+ * The Bearer form for `OTEL_EXPORTER_OTLP_HEADERS`. The space between `Bearer`
+ * and the token MUST be percent-encoded (`%20`) — an unescaped space breaks
+ * OTEL's `name=value` header parsing and silently drops auth. This is the fix
+ * for the previously wrong `Authorization=Bearer <key>` guidance.
+ */
+declare function otlpBearerHeaderValue(apiKey: string): string;
+interface OtlpSnippets {
+    /** OTLP endpoint + protocol + compression env vars pointed at the cloud origin. */
+    env: string;
+    /** Auth header carried by the exporter (X-Crumbtrail-Auth or Bearer). */
+    authHeader: string;
+    /** Resource attribute that files spans/logs into a Crumbtrail session. */
+    sessionAttr: string;
+    /** Human note about the appended /v1/traces + /v1/logs paths. */
+    note: string;
+}
+/**
+ * Build the OTLP setup snippets for a non-JS backend. Uses ONLY the real,
+ * documented names — no invented env vars or headers, and everything is derived
+ * from OTLP_CAPABILITY_FACTS so it can never drift from the collector recipes:
+ *   • OTEL_EXPORTER_OTLP_ENDPOINT   → the cloud origin (exporter appends paths)
+ *   • OTEL_EXPORTER_OTLP_PROTOCOL   → http/protobuf or http/json
+ *   • OTEL_EXPORTER_OTLP_HEADERS    → X-Crumbtrail-Auth=<key> (or Bearer%20<key>)
+ *   • OTEL_EXPORTER_OTLP_COMPRESSION→ none (recommended) — gzip is accepted too
+ *   • OTEL_RESOURCE_ATTRIBUTES      → crumbtrail.session.id=<id>
+ * Verified against docs/integrations/* and the ingest routes.
+ */
+declare function buildOtlpSnippets({ endpoint, apiKey, }: EndpointKey): OtlpSnippets;
+/**
+ * Build the "Install via AI" agent prompt — a copyable block with the real
+ * endpoint + key baked in. It instructs a coding agent to run the correct setup
+ * for the stack, initialize with PRESET_PASSIVE (JS), wire backend middleware
+ * when applicable, change nothing else, and verify the build.
+ */
+declare function buildAgentPrompt(stack: Stack, keys: EndpointKey): string;
+
+export { BACKEND_JS_STACKS, type EndpointKey, INFRA_STACKS, type InstallVariantKind, JS_STACKS, OTLP_CAPABILITY_FACTS, OTLP_STACKS, type OtlpCapabilityFacts, type OtlpSnippets, type StackInstall, allStackInstalls, buildAgentPrompt, buildBackendJsNote, buildOtlpSnippets, getInstallVariant, otlpAuthHeaderValue, otlpBearerHeaderValue };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { Stack } from 'crumbtrail-core';
+
+type InstallVariantKind = "js" | "otlp" | "infra";
+/** JS/TS stacks that install crumbtrail-core directly. */
+declare const JS_STACKS: readonly Stack[];
+/** JS backends that additionally wire the crumbtrail-node middleware. */
+declare const BACKEND_JS_STACKS: readonly Stack[];
+/** Non-JS backends wired via their existing OpenTelemetry exporter. */
+declare const OTLP_STACKS: readonly Stack[];
+/** Evidence sources that are not yet a first-class ingest target. */
+declare const INFRA_STACKS: readonly Stack[];
+interface StackInstall {
+    stack: Stack;
+    kind: InstallVariantKind;
+    /** True for express/hono/node — they also need the backend middleware note. */
+    backendJs: boolean;
+    /** True for infra evidence sources — surfaced as "coming soon". */
+    comingSoon: boolean;
+}
+/** Classify a single stack into its install variant. Total over all 18 stacks. */
+declare function getInstallVariant(stack: Stack): StackInstall;
+/** The classification table for every supported stack (handy for tests/UI). */
+declare function allStackInstalls(): StackInstall[];
+interface EndpointKey {
+    /** Live ingest endpoint (the cloud origin / dashboard origin). */
+    endpoint: string;
+    /** Live ingest key used as the auth token. */
+    apiKey: string;
+}
+/**
+ * The crumbtrail-node backend note shown under <InstallSteps/> for the backend-JS
+ * stacks. Uses ONLY the real crumbtrail-node exports — no invented names:
+ *   • Express is the only stack with framework middleware
+ *     (createCrumbtrailExpressMiddleware / createCrumbtrailExpressErrorMiddleware).
+ *   • Hono / Node ship no framework middleware, so they open a headless session
+ *     (startHeadlessSession) and record server-side events against it.
+ */
+declare function buildBackendJsNote(stack: Stack): string;
+/**
+ * Single source of truth for what Crumbtrail's OTLP/HTTP receiver accepts. Both
+ * `buildOtlpSnippets` (the wizard guidance) and the collector recipes in
+ * `packages/node/src/provider-recipes.json` must agree with these facts — a
+ * consistency test asserts the two never drift (compression, endpoint path
+ * suffix, auth header names).
+ *
+ * Nothing here is invented: the paths, protocols, auth headers, and session
+ * attribute all match the live ingest routes served by packages/node/src/server.ts
+ * and by the hosted Crumbtrail cloud.
+ */
+interface OtlpCapabilityFacts {
+    /** Signal paths the receiver serves; exporters append these to the endpoint. */
+    readonly paths: readonly ["/v1/traces", "/v1/logs"];
+    /** OTLP/HTTP wire protocols accepted (both, as of the protobuf+gzip parity CP). */
+    readonly protocols: readonly ["http/protobuf", "http/json"];
+    /** Auth header names honored equivalently by the receiver. */
+    readonly authHeaders: readonly ["X-Crumbtrail-Auth", "Authorization: Bearer"];
+    /** Content-Encoding posture: "none" recommended for collectors; gzip accepted. */
+    readonly compression: {
+        readonly recommended: "none";
+        readonly accepted: readonly ["none", "gzip"];
+    };
+    /** Resource/span attribute that files spans/logs into a Crumbtrail session. */
+    readonly sessionAttribute: "crumbtrail.session.id";
+}
+declare const OTLP_CAPABILITY_FACTS: OtlpCapabilityFacts;
+/**
+ * The `X-Crumbtrail-Auth=<key>` value for `OTEL_EXPORTER_OTLP_HEADERS`.
+ * OTEL parses that env var as comma-separated `name=value` pairs; the value is
+ * used verbatim, so a plain key needs no escaping here.
+ */
+declare function otlpAuthHeaderValue(apiKey: string): string;
+/**
+ * The Bearer form for `OTEL_EXPORTER_OTLP_HEADERS`. The space between `Bearer`
+ * and the token MUST be percent-encoded (`%20`) — an unescaped space breaks
+ * OTEL's `name=value` header parsing and silently drops auth. This is the fix
+ * for the previously wrong `Authorization=Bearer <key>` guidance.
+ */
+declare function otlpBearerHeaderValue(apiKey: string): string;
+interface OtlpSnippets {
+    /** OTLP endpoint + protocol + compression env vars pointed at the cloud origin. */
+    env: string;
+    /** Auth header carried by the exporter (X-Crumbtrail-Auth or Bearer). */
+    authHeader: string;
+    /** Resource attribute that files spans/logs into a Crumbtrail session. */
+    sessionAttr: string;
+    /** Human note about the appended /v1/traces + /v1/logs paths. */
+    note: string;
+}
+/**
+ * Build the OTLP setup snippets for a non-JS backend. Uses ONLY the real,
+ * documented names — no invented env vars or headers, and everything is derived
+ * from OTLP_CAPABILITY_FACTS so it can never drift from the collector recipes:
+ *   • OTEL_EXPORTER_OTLP_ENDPOINT   → the cloud origin (exporter appends paths)
+ *   • OTEL_EXPORTER_OTLP_PROTOCOL   → http/protobuf or http/json
+ *   • OTEL_EXPORTER_OTLP_HEADERS    → X-Crumbtrail-Auth=<key> (or Bearer%20<key>)
+ *   • OTEL_EXPORTER_OTLP_COMPRESSION→ none (recommended) — gzip is accepted too
+ *   • OTEL_RESOURCE_ATTRIBUTES      → crumbtrail.session.id=<id>
+ * Verified against docs/integrations/* and the ingest routes.
+ */
+declare function buildOtlpSnippets({ endpoint, apiKey, }: EndpointKey): OtlpSnippets;
+/**
+ * Build the "Install via AI" agent prompt — a copyable block with the real
+ * endpoint + key baked in. It instructs a coding agent to run the correct setup
+ * for the stack, initialize with PRESET_PASSIVE (JS), wire backend middleware
+ * when applicable, change nothing else, and verify the build.
+ */
+declare function buildAgentPrompt(stack: Stack, keys: EndpointKey): string;
+
+export { BACKEND_JS_STACKS, type EndpointKey, INFRA_STACKS, type InstallVariantKind, JS_STACKS, OTLP_CAPABILITY_FACTS, OTLP_STACKS, type OtlpCapabilityFacts, type OtlpSnippets, type StackInstall, allStackInstalls, buildAgentPrompt, buildBackendJsNote, buildOtlpSnippets, getInstallVariant, otlpAuthHeaderValue, otlpBearerHeaderValue };

package/dist/index.js

@@ -0,0 +1,191 @@
+// src/index.ts
+import { STACK_IDS } from "crumbtrail-core";
+var JS_STACKS = [
+  "nextjs",
+  "react",
+  "vue",
+  "svelte",
+  "vite",
+  "express",
+  "hono",
+  "node"
+];
+var BACKEND_JS_STACKS = ["express", "hono", "node"];
+var OTLP_STACKS = [
+  "django",
+  "flask",
+  "fastapi",
+  "dotnet",
+  "go",
+  "rails"
+];
+var INFRA_STACKS = [
+  "postgres",
+  "grafana",
+  "loki",
+  "docker"
+];
+function getInstallVariant(stack) {
+  const backendJs = BACKEND_JS_STACKS.includes(stack);
+  if (JS_STACKS.includes(stack)) {
+    return { stack, kind: "js", backendJs, comingSoon: false };
+  }
+  if (OTLP_STACKS.includes(stack)) {
+    return { stack, kind: "otlp", backendJs: false, comingSoon: false };
+  }
+  return { stack, kind: "infra", backendJs: false, comingSoon: true };
+}
+function allStackInstalls() {
+  return STACK_IDS.map(getInstallVariant);
+}
+function buildBackendJsNote(stack) {
+  if (stack === "express") {
+    return [
+      "// Backend (Express) \u2014 also capture server-side errors and requests.",
+      "// Reuse the same ingest endpoint + key you set on the SDK above.",
+      "import {",
+      "  createCrumbtrailExpressMiddleware,",
+      "  createCrumbtrailExpressErrorMiddleware,",
+      '} from "crumbtrail-node";',
+      "",
+      "const crumbtrailOptions = { endpoint: CRUMBTRAIL_ENDPOINT, authToken: CRUMBTRAIL_KEY };",
+      "app.use(createCrumbtrailExpressMiddleware(crumbtrailOptions));      // before your routes",
+      "app.use(createCrumbtrailExpressErrorMiddleware(crumbtrailOptions)); // after your routes",
+      "",
+      "// Prefer OpenTelemetry? Point your OTLP exporter at the receiver instead."
+    ].join("\n");
+  }
+  return [
+    "// Backend (Hono / Node) \u2014 crumbtrail-node ships no framework middleware here.",
+    "// Open a headless session and record server-side events against it:",
+    'import { startHeadlessSession } from "crumbtrail-node";',
+    "",
+    "const session = await startHeadlessSession({",
+    "  endpoint: CRUMBTRAIL_ENDPOINT,",
+    "  authToken: CRUMBTRAIL_KEY,",
+    '  sessionId: "<your-session-id>",',
+    "});",
+    "// session.record(event) to attach server events; session.end() when done.",
+    "",
+    "// Prefer OpenTelemetry? Point your OTLP exporter at the receiver instead."
+  ].join("\n");
+}
+var OTLP_CAPABILITY_FACTS = {
+  paths: ["/v1/traces", "/v1/logs"],
+  protocols: ["http/protobuf", "http/json"],
+  authHeaders: ["X-Crumbtrail-Auth", "Authorization: Bearer"],
+  compression: { recommended: "none", accepted: ["none", "gzip"] },
+  sessionAttribute: "crumbtrail.session.id"
+};
+function otlpAuthHeaderValue(apiKey) {
+  return `X-Crumbtrail-Auth=${apiKey}`;
+}
+function otlpBearerHeaderValue(apiKey) {
+  return `Authorization=Bearer%20${apiKey}`;
+}
+function buildOtlpSnippets({
+  endpoint,
+  apiKey
+}) {
+  const [protobuf, jsonProtocol] = OTLP_CAPABILITY_FACTS.protocols;
+  return {
+    env: [
+      `OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint}`,
+      `OTEL_EXPORTER_OTLP_PROTOCOL=${protobuf}   # or ${jsonProtocol}`,
+      `OTEL_EXPORTER_OTLP_COMPRESSION=${OTLP_CAPABILITY_FACTS.compression.recommended}   # recommended; gzip is also accepted`
+    ].join("\n"),
+    authHeader: [
+      `OTEL_EXPORTER_OTLP_HEADERS=${otlpAuthHeaderValue(apiKey)}`,
+      `# Or, if your exporter sends a Bearer token (note the %20-escaped space):`,
+      `# OTEL_EXPORTER_OTLP_HEADERS=${otlpBearerHeaderValue(apiKey)}`
+    ].join("\n"),
+    sessionAttr: `OTEL_RESOURCE_ATTRIBUTES=${OTLP_CAPABILITY_FACTS.sessionAttribute}=<your-session-id>`,
+    note: `Crumbtrail's OTLP receiver appends ${OTLP_CAPABILITY_FACTS.paths.join(" and ")} to the endpoint above \u2014 don't include those paths yourself. Set the ${OTLP_CAPABILITY_FACTS.sessionAttribute} resource attribute to join backend spans to the frontend session.`
+  };
+}
+function buildAgentPrompt(stack, keys) {
+  const { kind, backendJs } = getInstallVariant(stack);
+  const { endpoint, apiKey } = keys;
+  const header = [
+    "You are setting up Crumbtrail in this project. Make ONLY the changes below,",
+    "do not refactor or touch anything else, then verify the build still passes.",
+    "",
+    `Ingest endpoint: ${endpoint}`,
+    `Ingest key:      ${apiKey}`,
+    ""
+  ];
+  if (kind === "otlp") {
+    return [
+      ...header,
+      "This is a non-JS backend that already uses OpenTelemetry. Do NOT install a",
+      "second SDK. Instead, add Crumbtrail as an additional OTLP/HTTP exporter:",
+      `  1. Set OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint} (the exporter appends`,
+      "     /v1/traces and /v1/logs \u2014 do not add those paths).",
+      `  2. Send the auth header X-Crumbtrail-Auth: ${apiKey} on every export`,
+      "     (or Authorization: Bearer <key> if your exporter prefers that).",
+      "  3. Stamp the resource attribute crumbtrail.session.id so spans/logs join",
+      "     the right session.",
+      "  4. Keep your existing exporter \u2014 add Crumbtrail alongside it.",
+      "  5. Verify the app still builds and starts."
+    ].join("\n");
+  }
+  const jsLines = [
+    ...header,
+    "This is a JavaScript/TypeScript project. Do the following:",
+    "  1. Install the SDK:  npm install crumbtrail-core",
+    '  2. Import the SDK:  import { Crumbtrail, PRESET_PASSIVE } from "crumbtrail-core";',
+    "  3. Initialize once at the app entry point with PRESET_PASSIVE:",
+    "       Crumbtrail.init({",
+    "         ...PRESET_PASSIVE,",
+    `         httpEndpoint: "${endpoint}",`,
+    `         httpAuthToken: "${apiKey}",`,
+    "       });"
+  ];
+  if (backendJs && stack === "express") {
+    jsLines.push(
+      "  4. This is an Express backend \u2014 also install crumbtrail-node and capture",
+      "     server errors and requests with its Express middleware:",
+      "       import {",
+      "         createCrumbtrailExpressMiddleware,",
+      "         createCrumbtrailExpressErrorMiddleware,",
+      '       } from "crumbtrail-node";',
+      `       const opts = { endpoint: "${endpoint}", authToken: "${apiKey}" };`,
+      "       app.use(createCrumbtrailExpressMiddleware(opts));      // before your routes",
+      "       app.use(createCrumbtrailExpressErrorMiddleware(opts)); // after your routes",
+      "  5. Change nothing else, then verify the build still passes."
+    );
+  } else if (backendJs) {
+    jsLines.push(
+      "  4. This is also a backend. Install crumbtrail-node; it ships no framework",
+      "     middleware for this stack, so open a headless session and record",
+      "     server-side events against it:",
+      '       import { startHeadlessSession } from "crumbtrail-node";',
+      "       const session = await startHeadlessSession({",
+      `         endpoint: "${endpoint}",`,
+      `         authToken: "${apiKey}",`,
+      '         sessionId: "<your-session-id>",',
+      "       });",
+      "       // session.record(event) for server events; session.end() when the request ends.",
+      "  5. Change nothing else, then verify the build still passes."
+    );
+  } else {
+    jsLines.push(
+      "  4. Change nothing else, then verify the build still passes."
+    );
+  }
+  return jsLines.join("\n");
+}
+export {
+  BACKEND_JS_STACKS,
+  INFRA_STACKS,
+  JS_STACKS,
+  OTLP_CAPABILITY_FACTS,
+  OTLP_STACKS,
+  allStackInstalls,
+  buildAgentPrompt,
+  buildBackendJsNote,
+  buildOtlpSnippets,
+  getInstallVariant,
+  otlpAuthHeaderValue,
+  otlpBearerHeaderValue
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "crumbtrail-install-shared",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "crumbtrail-core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/crumbtrail-dev/crumbtrail-js/tree/main/packages/install-shared#readme",
+  "bugs": {
+    "url": "https://github.com/crumbtrail-dev/crumbtrail-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crumbtrail-dev/crumbtrail-js.git",
+    "directory": "packages/install-shared"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}