@agenthoney/analytics 0.0.0-stage → 0.14.0

package/dist/core/transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The seam between the collector and the network.
+ *
+ * Exists so the collector can be tested without a socket, and so a runtime
+ * without `fetch` can supply its own. The three-way outcome below is the
+ * important part of the contract.
+ */
+export type SendOutcome = {
+    outcome: "accepted";
+    status: number;
+}
+/**
+ * A 4xx that is not 408 or 429: our payload is wrong.
+ *
+ * ⚠️ **Drop the batch. Do not retry, and do not count it against the
+ * breaker.** Retrying a body the server has already judged malformed just
+ * sends it again, and treating it as an outage would let one bad field
+ * silence all telemetry for thirty seconds at a time while the endpoint is
+ * perfectly healthy. This is the same distinction maxidomo-app's
+ * `ExpectedError` draws: a failure somebody wrote on purpose is not an
+ * incident.
+ */
+ | {
+    outcome: "rejected";
+    status: number;
+}
+/** Network error, timeout, 408, 429 or 5xx. Retry, and count it. */
+ | {
+    outcome: "retryable";
+    status?: number;
+    retryAfterMs?: number;
+};
+export interface Transport {
+    send(body: string, headers: Readonly<Record<string, string>>, signal: AbortSignal): Promise<SendOutcome>;
+}
+/** Map an HTTP status onto the outcome taxonomy above. */
+export declare function outcomeForStatus(status: number, retryAfterMs?: number): SendOutcome;
+/**
+ * The default transport: `fetch`, which every supported runtime has.
+ *
+ * ⚠️ It never throws. A thrown transport would reach the flush loop, and a
+ * flush loop that can throw is one unhandled rejection away from taking a
+ * customer's process down with it.
+ */
+export declare function fetchTransport(url: string): Transport;