spanport 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# spanport (Node.js SDK)
 
-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.
+Send your Node.js app's logs to Spanport. Keep logging the way you already do.
+
+```bash
+npm install spanport
+```
+
+```js
+import * as spanport from "spanport";
+
+spanport.init({
+  // From Setup → API keys → Data keys in Spanport (shown once)
+  dataKey: "sp_ingest_...",
+  service: "orders-api",
+  // Defaults: http://localhost:4318 and http://localhost:8000
+  collectorUrl: "https://spanport-collector.example.com",
+  serverUrl: "https://spanport.example.com",
+});
+
+console.error("Payment failed for order 1042"); // sent automatically
+```
+
+**pino and winston** write JSON lines to `spanport.logStream()`:
+
+```js
+import pino from "pino";
+const logger = pino(pino.multistream([{ stream: process.stdout }, { stream: spanport.logStream() }]));
+
+import winston from "winston";
+const logger = winston.createLogger({
+  format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.Stream({ stream: spanport.logStream() }),
+  ],
+});
+```
+
+- **`console.debug/log/info/warn/error` are sent automatically**; what your app prints doesn't change. Turn this off with `captureConsole: false`.
+- **Logs are sent in the background**, in batches. A normal exit sends what is left; on `SIGTERM`, send it yourself: `process.on("SIGTERM", async () => { await spanport.shutdown(); process.exit(0); })`.
+- **Logs inside an OpenTelemetry span** carry its `trace_id` and `span_id`; so do pino lines that include them.
+- **Wrong key?** At start-up the SDK asks the server once whether the key is valid and prints a clear error on stderr if not. Pass `checkKey: false` if the app cannot reach the server.
+- **Use `https://` for anything beyond your own machine or Docker network.** The data key is sent with every batch.
+- **It never breaks your app.** `init()` never throws; setup and key problems are printed on stderr as `spanport: ...` and the app carries on. An unreachable collector is not reported yet (see [Troubleshooting](#nothing-arrives-and-there-is-no-error)).
+
+Node.js 22.15 or newer. ES module; CommonJS apps can `require("spanport")`.
+
+At start-up the SDK prints, on stderr:
+
+```
+INFO spanport: sending logs for service orders-api to http://localhost:4318
+INFO spanport: data key ...a1b2 accepted
+```
+
+If the second line is missing or says something else, see [Troubleshooting](#troubleshooting).
+
+## What Spanport receives
+
+| You write | Message | Level | Fields you can filter on |
+| --- | --- | --- | --- |
+| `console.log("Paid", { orderId: 7 })` | `Paid { orderId: 7 }` (as the terminal shows it) | `debug` DEBUG, `log`/`info` INFO, `warn` WARN, `error` ERROR | none: objects become part of the text |
+| pino `logger.info({ "user.id": "u42" }, "Paid")` | `Paid` | pino's level (`fatal` is FATAL, `trace` is TRACE) | every other key, e.g. `user.id` |
+| winston `logger.info("Paid", { "user.id": "u42" })` | `Paid` | winston's level (`http` is INFO, `verbose` is DEBUG) | every other key |
+
+- **Use flat, dotted names for fields**: `{ "user.id": "u42" }`, not `{ user: { id: "u42" } }`. A nested object arrives as one field (`user`) holding JSON text, so the User ID filter can't see it.
+- Spanport's **Client IP** and **User ID** filters read the fields `client.ip` and `user.id`. Every line also has `log.source` (`console` or `stream`) and the `service` you passed to `init()`.
+- Errors: `console.error(err)` and pino's `logger.error(err)` both keep the stack trace in the message.
+
+## Finding logs in Spanport
+
+Pick the project and time range first; a search only looks inside that range.
+
+- **Message contains** finds any part of the text, ignoring case. `nitish` finds `GET /api/files 200 12ms user=nitish@acme.com`; `nitishbharadwaj` doesn't, because those letters never appear together in that line.
+- **User ID is u42** and **Client IP is ...** work only for lines that carry the `user.id` / `client.ip` fields (pino or winston, see above). A user written inside the message text is found with Message contains instead.
+- **Any other field** you send: choose "Type a query instead" and write `field:value`, e.g. `order.id:1042` or `tenant:acme*` (`*` is a wildcard). In a query, a plain word matches a whole word: `timeout` finds "request timeout" but not "timeouts"; use `timeout*` for that.
+- Expand a line to see all its fields, with Filter and Exclude next to each.
+
+## Troubleshooting
+
+### Nothing arrives and there is no error
+
+The SDK checks the data key, not the collector. If `collectorUrl` is wrong or the collector is down, batches are dropped **without a message**. Check that the collector answers from where the app runs:
+
+```bash
+curl -i -X POST http://localhost:4318/v1/logs -H "Content-Type: application/json" -d "{}"
+```
+
+Any HTTP answer (e.g. `200`) means it is reachable; "connection refused" means it isn't. An app running in Docker can't reach the host's `localhost`: use `http://host.docker.internal:4318`, or `http://collector:4318` on the Spanport Compose network. Also check the Logs page shows the right project and a time range that includes now.
+
+### Searching for a name or id finds nothing
+
+Search finds only text that is in the line. Expand a line you expect to match and look at its message and fields: if the user appears as `user=nitish@acme.com` inside the message, search **Message contains** `nitish@acme.com`; to use the **User ID** filter, send `user.id` as a field (see [What Spanport receives](#what-spanport-receives)).
+
+### NestJS errors show in the terminal but not in Spanport
+
+Nest's built-in logger writes straight to `process.stdout`/`process.stderr`, not through `console`, so the SDK never sees its lines. That includes `ERROR [ExceptionsHandler] ...` for every unhandled exception. Route Nest's logger through `console` and they arrive with the right level (and stack trace), while the terminal output stays the same:
+
+```ts
+// src/common/logger/console-routed.logger.ts
+import { LoggerService } from "@nestjs/common";
+
+function asText(value: unknown): string {
+  if (value instanceof Error) return value.stack ?? value.message;
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+// Nest passes the context last; a value with line breaks is a stack trace, not a context.
+function formatLine(message: unknown, optionalParams: unknown[]): string {
+  const lastParam = optionalParams.at(-1);
+  const context = typeof lastParam === "string" && !lastParam.includes("\n") ? lastParam : undefined;
+  const extraValues = context === undefined ? optionalParams : optionalParams.slice(0, -1);
+  const firstLine = context ? `[${context}] ${asText(message)}` : asText(message);
+  return [firstLine, ...extraValues.map(asText)].join("\n");
+}
+
+export class ConsoleRoutedLogger implements LoggerService {
+  log(message: unknown, ...params: unknown[]) { console.log(formatLine(message, params)); }
+  warn(message: unknown, ...params: unknown[]) { console.warn(formatLine(message, params)); }
+  error(message: unknown, ...params: unknown[]) { console.error(formatLine(message, params)); }
+  fatal(message: unknown, ...params: unknown[]) { console.error(formatLine(message, params)); }
+  debug(message: unknown, ...params: unknown[]) { console.debug(formatLine(message, params)); }
+  verbose(message: unknown, ...params: unknown[]) { console.debug(formatLine(message, params)); }
+}
+```
+
+```ts
+// main.ts
+const app = await NestFactory.create(AppModule, { logger: new ConsoleRoutedLogger() });
+```
+
+The same applies to any library that writes to `process.stdout` directly: give it a logger that uses `console`, pino or winston.
+
+### Failed requests show as INFO
+
+Every `console.log` line is INFO, whatever its text says. A request logger should pick the method by status, so the ERROR and WARN cards on the Logs page count failed calls:
+
+```ts
+const writeLine = status >= 500 ? console.error : status >= 400 ? console.warn : console.log;
+writeLine(`${method} ${url} ${status} ${durationMs}ms`);
+```
+
+### "data key ...xxxx was rejected"
+
+The server doesn't know the key: it was mistyped, revoked, deleted, belongs to an archived project, or is an admin key (`sp_admin_...`) instead of a data key (`sp_ingest_...`). Check it with:
+
+```bash
+curl -i http://localhost:8000/api/v1/api-keys/current -H "Authorization: Bearer sp_ingest_..."
+```
+
+`200` means the key is fine; `401` means create a new data key on the API keys page (it is shown once) and restart the app with it.
+
+### Client IP and user are empty
+
+The SDK sends only what a log line carries. Add them as fields named `client.ip` and `user.id`, e.g. with pino: `logger.error({ "client.ip": req.ip, "user.id": userId }, "Payment failed")`. Behind a proxy, read the client address from `X-Forwarded-For` (`app.set("trust proxy", true)` in Express).
+
+### "could not reach ... to check data key"
+
+The key check couldn't reach `serverUrl` (default `http://localhost:8000`). Logs are still sent to the collector, but nobody has confirmed the key. Point `serverUrl` at the Spanport server, or pass `checkKey: false` if the app has no route to it.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run lint
+npm run typecheck
+npm run build
+```

package/dist/consoleCapture.d.ts

@@ -0,0 +1,14 @@
+/** Copies console.debug/log/info/warn/error calls to Spanport. The app's console output is unchanged. */
+import { type ConsoleMethod } from "./severity.js";
+/**
+ * Wrap the console methods so each call is also passed to `onLog`.
+ *
+ * The original method always runs first. A failure in `onLog` is ignored on purpose: the app's
+ * console must keep working whatever happens to Spanport. A call made while `onLog` is running
+ * (e.g. by an exporter that logs) is not passed on again, so it can't loop.
+ *
+ * @param onLog - Receives the method and the formatted message, as console would print it.
+ * @returns A function that puts the original console methods back.
+ */
+export declare function captureConsole(onLog: (method: ConsoleMethod, message: string) => void): () => void;
+//# sourceMappingURL=consoleCapture.d.ts.map

package/dist/consoleCapture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consoleCapture.d.ts","sourceRoot":"","sources":["../src/consoleCapture.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAKzG,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAwBlG"}

package/dist/consoleCapture.js

@@ -0,0 +1,44 @@
+/** Copies console.debug/log/info/warn/error calls to Spanport. The app's console output is unchanged. */
+import { format } from "node:util";
+import { CAPTURED_CONSOLE_METHODS } from "./constants.js";
+import {} from "./severity.js";
+/**
+ * Wrap the console methods so each call is also passed to `onLog`.
+ *
+ * The original method always runs first. A failure in `onLog` is ignored on purpose: the app's
+ * console must keep working whatever happens to Spanport. A call made while `onLog` is running
+ * (e.g. by an exporter that logs) is not passed on again, so it can't loop.
+ *
+ * @param onLog - Receives the method and the formatted message, as console would print it.
+ * @returns A function that puts the original console methods back.
+ */
+export function captureConsole(onLog) {
+    const originals = new Map();
+    let passingOn = false;
+    for (const method of CAPTURED_CONSOLE_METHODS) {
+        // Kept as-is so restore puts back the exact original; always called with console as `this`.
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        const original = console[method];
+        originals.set(method, original);
+        console[method] = (...args) => {
+            original.apply(console, args);
+            if (passingOn)
+                return;
+            passingOn = true;
+            try {
+                onLog(method, format(...args));
+            }
+            catch {
+                // Never let Spanport break the app's console.
+            }
+            finally {
+                passingOn = false;
+            }
+        };
+    }
+    return () => {
+        for (const [method, original] of originals)
+            console[method] = original;
+    };
+}
+//# sourceMappingURL=consoleCapture.js.map

package/dist/consoleCapture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consoleCapture.js","sourceRoot":"","sources":["../src/consoleCapture.ts"],"names":[],"mappings":"AAAA,yGAAyG;AAEzG,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAsB,MAAM,eAAe,CAAC;AAInD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,KAAuD;IACpF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC5D,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,MAAM,IAAI,wBAAwB,EAAE,CAAC;QAC9C,4FAA4F;QAC5F,6DAA6D;QAC7D,MAAM,QAAQ,GAAoB,OAAO,CAAC,MAAM,CAAC,CAAC;QAClD,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAe,EAAQ,EAAE;YAC7C,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC9B,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC;gBACH,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;oBAAS,CAAC;gBACT,SAAS,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,EAAE;QACV,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;IACzE,CAAC,CAAC;AACJ,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,38 @@
+/** SDK constants. Code refers to these by name, never by inline value. */
+export declare const DATA_KEY_PREFIX = "sp_ingest_";
+export declare const DEFAULT_COLLECTOR_URL = "http://localhost:4318";
+export declare const DEFAULT_SERVER_URL = "http://localhost:8000";
+export declare const OTLP_LOGS_PATH = "/v1/logs";
+export declare const CURRENT_API_KEY_PATH = "/api/v1/api-keys/current";
+export declare const AUTHORIZATION_HEADER = "Authorization";
+export declare const BEARER_PREFIX = "Bearer ";
+export declare const ALLOWED_URL_PROTOCOLS: readonly string[];
+export declare const KEY_CHECK_TIMEOUT_MS = 5000;
+export declare const VISIBLE_KEY_SUFFIX_LENGTH = 4;
+export declare const HTTP_UNAUTHORIZED = 401;
+/** console methods the SDK copies to Spanport; the original output is unchanged. */
+export declare const CAPTURED_CONSOLE_METHODS: readonly ["debug", "log", "info", "warn", "error"];
+/** pino's numeric levels (pino's own defaults). */
+export declare const PINO_TRACE = 10;
+export declare const PINO_DEBUG = 20;
+export declare const PINO_INFO = 30;
+export declare const PINO_WARN = 40;
+export declare const PINO_ERROR = 50;
+export declare const PINO_FATAL = 60;
+export declare const SERVICE_NAME_ATTRIBUTE = "service.name";
+/** Instrumentation scope name on every log record the SDK emits. */
+export declare const SDK_SCOPE_NAME = "spanport";
+/** Prefix on the SDK's own stderr messages, which are never exported. */
+export declare const SDK_MESSAGE_PREFIX = "spanport:";
+/** Where a log came from, recorded as the `log.source` attribute. */
+export declare const LOG_SOURCE_ATTRIBUTE = "log.source";
+export declare const CONSOLE_SOURCE = "console";
+export declare const LOG_STREAM_SOURCE = "stream";
+/** Fields of a pino or winston JSON line that become part of the record rather than attributes. */
+export declare const MESSAGE_FIELDS: readonly string[];
+export declare const LEVEL_FIELD = "level";
+export declare const TIME_FIELDS: readonly string[];
+export declare const TRACE_ID_FIELD = "trace_id";
+export declare const SPAN_ID_FIELD = "span_id";
+export declare const LINE_SEPARATOR = "\n";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAC1D,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAC/D,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAC5E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,oDAAqD,CAAC;AAE3F,mDAAmD;AACnD,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AACrD,oEAAoE;AACpE,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,eAAe,CAAC;AACjD,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,mGAAmG;AACnG,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAuB,CAAC;AACpE,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAA0B,CAAC;AACpE,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,cAAc,OAAO,CAAC"}

package/dist/constants.js

@@ -0,0 +1,38 @@
+/** SDK constants. Code refers to these by name, never by inline value. */
+export const DATA_KEY_PREFIX = "sp_ingest_";
+export const DEFAULT_COLLECTOR_URL = "http://localhost:4318";
+export const DEFAULT_SERVER_URL = "http://localhost:8000";
+export const OTLP_LOGS_PATH = "/v1/logs";
+export const CURRENT_API_KEY_PATH = "/api/v1/api-keys/current";
+export const AUTHORIZATION_HEADER = "Authorization";
+export const BEARER_PREFIX = "Bearer ";
+export const ALLOWED_URL_PROTOCOLS = ["http:", "https:"];
+export const KEY_CHECK_TIMEOUT_MS = 5000;
+export const VISIBLE_KEY_SUFFIX_LENGTH = 4;
+export const HTTP_UNAUTHORIZED = 401;
+/** console methods the SDK copies to Spanport; the original output is unchanged. */
+export const CAPTURED_CONSOLE_METHODS = ["debug", "log", "info", "warn", "error"];
+/** pino's numeric levels (pino's own defaults). */
+export const PINO_TRACE = 10;
+export const PINO_DEBUG = 20;
+export const PINO_INFO = 30;
+export const PINO_WARN = 40;
+export const PINO_ERROR = 50;
+export const PINO_FATAL = 60;
+export const SERVICE_NAME_ATTRIBUTE = "service.name";
+/** Instrumentation scope name on every log record the SDK emits. */
+export const SDK_SCOPE_NAME = "spanport";
+/** Prefix on the SDK's own stderr messages, which are never exported. */
+export const SDK_MESSAGE_PREFIX = "spanport:";
+/** Where a log came from, recorded as the `log.source` attribute. */
+export const LOG_SOURCE_ATTRIBUTE = "log.source";
+export const CONSOLE_SOURCE = "console";
+export const LOG_STREAM_SOURCE = "stream";
+/** Fields of a pino or winston JSON line that become part of the record rather than attributes. */
+export const MESSAGE_FIELDS = ["msg", "message"];
+export const LEVEL_FIELD = "level";
+export const TIME_FIELDS = ["time", "timestamp"];
+export const TRACE_ID_FIELD = "trace_id";
+export const SPAN_ID_FIELD = "span_id";
+export const LINE_SEPARATOR = "\n";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,qBAAqB,GAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAE3F,mDAAmD;AACnD,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAC7B,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC;AAE7B,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,oEAAoE;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AACzC,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAAC;AAE9C,qEAAqE;AACrE,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AACjD,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAE1C,mGAAmG;AACnG,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAsB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Spanport SDK: send your Node.js app's logs to Spanport.
+ *
+ *     import * as spanport from "spanport";
+ *     spanport.init({ dataKey: "sp_ingest_...", service: "orders-api" });
+ *
+ * It never breaks the host app: init() never throws, logs are sent in the background, and if
+ * anything is wrong it says so on stderr and the app carries on.
+ */
+import { type Writable } from "node:stream";
+export interface SpanportOptions {
+    /** The project's data key (sp_ingest_...). */
+    dataKey: string;
+    /** Name of this app as shown in Spanport, e.g. "orders-api". */
+    service: string;
+    /** The Spanport OTel Collector (OTLP/HTTP). Default http://localhost:4318. */
+    collectorUrl?: string;
+    /** The Spanport server, asked once whether the data key is valid. Default http://localhost:8000. */
+    serverUrl?: string;
+    /** Set false to skip the start-up key check (e.g. no route to the server). Default true. */
+    checkKey?: boolean;
+    /** Set false to stop copying console.* calls to Spanport. Default true. */
+    captureConsole?: boolean;
+}
+/**
+ * Start sending this app's logs to Spanport. Call once at start-up. Never throws.
+ *
+ * @param options - Data key, service name and where Spanport runs.
+ */
+export declare function init(options: SpanportOptions): void;
+/**
+ * Send any logs still queued, stop capturing console and stop. Safe to call more than once.
+ * Call it on SIGTERM; a normal exit calls it for you. Never rejects.
+ */
+export declare function shutdown(): Promise<void>;
+/**
+ * A stream for pino or winston (JSON lines). Lines written before init() or after shutdown()
+ * are dropped.
+ *
+ *     pino(spanport.logStream())
+ *     new winston.transports.Stream({ stream: spanport.logStream() })
+ *
+ * @returns A new writable stream.
+ */
+export declare function logStream(): Writable;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAqB5C,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAWD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAMnD;AAED;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAU9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAIpC"}