@cowliss/sdk 0.1.1 → 0.3.0

package/README.md

@@ -48,8 +48,16 @@ per call when a single process writes into more than one app.
 Retries are handled for you. A call that fails to reach Cowliss, or that
 Cowliss could not complete, backs off and tries twice more; a generated
 `messageId` travels with every track, so a retry after a lost response never
-writes the event twice. A call Cowliss rejected is not retried: it throws a
-`CowError` carrying the reason.
+writes the event twice. Each attempt has a deadline of its own (`timeoutMs`,
+ten seconds by default, thirty for a batch), so a stalled Cowliss cannot
+hold up your code. A
+call Cowliss rejected is not retried: it throws a `CowError` carrying the
+reason.
+
+You do not have to wait for a call. `await cow.track(...)` throws on failure,
+as it always has; `cow.track(...)` on its own returns immediately and can
+never take your process down with an unhandled rejection. Pass `onError` to
+see the failures a call you did not await would otherwise swallow.
 
 ## Docs
 

package/dist/index.d.ts

@@ -12,6 +12,15 @@ export type * from "./types.js";
  * response dedupes instead of double-writing); network errors and 5xx retry with exponential backoff;
  * 4xx surface as typed CowErrors with the API's error-code enum, never
  * retried.
+ *
+ * Calling Cowliss must never take the caller's app with it, so the client is
+ * safe to use without awaiting. Every attempt carries a `timeoutMs` deadline
+ * (10s by default, 30s for a batch) so a stalled request cannot hang a
+ * caller for undici's
+ * multi-minute default, and every call marks its own rejection handled, so a
+ * deliberate fire-and-forget `cow.track(...)` cannot crash the process with
+ * an unhandled rejection. Awaiting still throws the CowError, and `onError`
+ * gives the fire-and-forget caller somewhere to see failures.
  */
 export declare class CowError extends Error {
     readonly code: ErrorCode | "network_error";
@@ -35,6 +44,27 @@ export type CowOptions = {
     baseUrl?: string;
     /** Retries after the initial attempt on network errors / 5xx. Default 2. */
     maxRetries?: number;
+    /**
+     * Deadline for one identify or track attempt, in milliseconds. Default
+     * 10000, so a call that exhausts the default retries gives up after ~30s
+     * instead of inheriting the runtime's multi-minute default. A timed-out
+     * attempt retries and finally surfaces as a `network_error` CowError.
+     */
+    timeoutMs?: number;
+    /**
+     * The same, for one `batch` attempt. Default 30000: a batch carries up to
+     * `MAX_BATCH_ITEMS` rows, so it is a slower request by design and holding
+     * it to the single-write deadline would abort imports that are finishing
+     * fine. Raise it for a large or slow import.
+     */
+    batchTimeoutMs?: number;
+    /**
+     * Called with the CowError of any failed call. Only useful to a caller who
+     * does not await, since an awaited call throws the same error; this is
+     * where a fire-and-forget `cow.track(...)` gets logged. Anything it throws
+     * is swallowed.
+     */
+    onError?: (error: CowError) => void;
     /** Injectable for tests and non-fetch runtimes. */
     fetch?: typeof globalThis.fetch;
 };
@@ -55,7 +85,7 @@ export declare class Cow {
     /**
      * Tracks one event. A messageId is generated when the caller does not
      * supply one, and sent both in the body and as the Idempotency-Key, so a
-     * retried request (network error, 5xx, or lost response) dedupes
+     * retried request (network error, timeout, 5xx, or lost response) dedupes
      * server-side. Historical timestamps pass through for backfill scripts.
      */
     track(input: WithDefaultSource<TrackInput>): Promise<EventDto>;

package/dist/index.js

@@ -13,6 +13,15 @@ const CLIENT_ID = `@cowliss/sdk/${SDK_VERSION}`;
  * response dedupes instead of double-writing); network errors and 5xx retry with exponential backoff;
  * 4xx surface as typed CowErrors with the API's error-code enum, never
  * retried.
+ *
+ * Calling Cowliss must never take the caller's app with it, so the client is
+ * safe to use without awaiting. Every attempt carries a `timeoutMs` deadline
+ * (10s by default, 30s for a batch) so a stalled request cannot hang a
+ * caller for undici's
+ * multi-minute default, and every call marks its own rejection handled, so a
+ * deliberate fire-and-forget `cow.track(...)` cannot crash the process with
+ * an unhandled rejection. Awaiting still throws the CowError, and `onError`
+ * gives the fire-and-forget caller somewhere to see failures.
  */
 export class CowError extends Error {
     code;
@@ -25,18 +34,28 @@ export class CowError extends Error {
     }
 }
 const RETRY_BASE_DELAY_MS = 100;
+/** See {@link CowOptions.timeoutMs}. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** See {@link CowOptions.batchTimeoutMs}. */
+const DEFAULT_BATCH_TIMEOUT_MS = 30_000;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class Cow {
     #apiKey;
     #sourceId;
     #baseUrl;
     #maxRetries;
+    #timeoutMs;
+    #batchTimeoutMs;
+    #onError;
     #fetch;
     constructor(options) {
         this.#apiKey = options.apiKey;
         this.#sourceId = options.sourceId;
         this.#baseUrl = options.baseUrl ?? "http://localhost:3400";
         this.#maxRetries = options.maxRetries ?? 2;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#batchTimeoutMs = options.batchTimeoutMs ?? DEFAULT_BATCH_TIMEOUT_MS;
+        this.#onError = options.onError;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
     /**
@@ -51,20 +70,46 @@ export class Cow {
         }
         return sourceId;
     }
-    async identify(input) {
-        return this.#post("/v1/identify", {
-            data: { ...input, sourceId: this.#sourceFor(input) },
+    /**
+     * Runs one call and marks its rejection handled, so a caller who
+     * deliberately does not await (`cow.track(...)` on a request path) can
+     * never take the process down with an unhandled rejection. The promise
+     * handed back is the original one, so awaiting still throws the CowError.
+     *
+     * This wraps at the public method, not inside `#post`, because
+     * `#sourceFor` throws before a request is ever made. The public methods
+     * are deliberately not `async` for the same reason: an `async` wrapper
+     * would hand the caller a second, unwatched promise and void the
+     * guarantee.
+     */
+    #watch(run) {
+        const promise = run();
+        promise.catch((error) => {
+            try {
+                this.#onError?.(error);
+            }
+            catch {
+                // An onError that throws must not become the crash we just prevented.
+            }
         });
+        return promise;
+    }
+    identify(input) {
+        return this.#watch(async () => this.#post("/v1/identify", {
+            data: { ...input, sourceId: this.#sourceFor(input) },
+        }));
     }
     /**
      * Tracks one event. A messageId is generated when the caller does not
      * supply one, and sent both in the body and as the Idempotency-Key, so a
-     * retried request (network error, 5xx, or lost response) dedupes
+     * retried request (network error, timeout, 5xx, or lost response) dedupes
      * server-side. Historical timestamps pass through for backfill scripts.
      */
-    async track(input) {
-        const messageId = input.messageId ?? crypto.randomUUID();
-        return this.#post("/v1/track", { data: { ...input, sourceId: this.#sourceFor(input), messageId } }, messageId);
+    track(input) {
+        return this.#watch(async () => {
+            const messageId = input.messageId ?? crypto.randomUUID();
+            return this.#post("/v1/track", { data: { ...input, sourceId: this.#sourceFor(input), messageId } }, messageId);
+        });
     }
     /**
      * Batch import: one source's identify and track calls in one request.
@@ -72,12 +117,10 @@ export class Cow {
      * the SDK does not generate one here, so re-running the same backfill
      * (same messageIds) dedupes instead of double-writing.
      */
-    async batch(input) {
-        return this.#post("/v1/batch", {
-            data: { ...input, sourceId: this.#sourceFor(input) },
-        });
+    batch(input) {
+        return this.#watch(async () => this.#post("/v1/batch", { data: { ...input, sourceId: this.#sourceFor(input) } }, undefined, this.#batchTimeoutMs));
     }
-    async #post(path, body, idempotencyKey) {
+    async #post(path, body, idempotencyKey, timeoutMs = this.#timeoutMs) {
         for (let attempt = 0;; attempt++) {
             let res;
             try {
@@ -90,7 +133,15 @@ export class Cow {
                         ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
                     },
                     body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(timeoutMs),
                 });
+                // Reading the body is part of the attempt: an abort or a truncated
+                // response mid-read is a transport failure like any other, and
+                // retrying it is safe (track carries its Idempotency-Key, identify
+                // upserts on identifiers).
+                if (res.ok) {
+                    return (await res.json()).data;
+                }
             }
             catch (cause) {
                 if (attempt < this.#maxRetries) {
@@ -99,9 +150,6 @@ export class Cow {
                 }
                 throw new CowError("network_error", "Network error", 0, { cause });
             }
-            if (res.ok) {
-                return (await res.json()).data;
-            }
             if (res.status >= 500 && attempt < this.#maxRetries) {
                 await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
                 continue;

package/dist/version.autogenerated.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "0.1.1";
+export declare const SDK_VERSION = "0.3.0";

package/dist/version.autogenerated.js

@@ -1,2 +1,2 @@
 // Generated by scripts/version.ts from package.json. Do not edit.
-export const SDK_VERSION = "0.1.1";
+export const SDK_VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowliss/sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {