@chirpier/chirpier-js 0.1.6 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chirpier/chirpier-js",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Chirpier SDK for JavaScript",
   "keywords": [
     "chirpier",
@@ -30,9 +30,10 @@
     "async-lock": "^1.4.1",
     "axios": "^0.24.0",
     "axios-retry": "^4.5.0",
-    "js-base64": "^3.7.7",
+    "dotenv": "^16.4.7",
     "ts-node": "^10.9.2",
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.15.0",
@@ -41,13 +42,12 @@
     "@types/jest": "^29.5.13",
     "@types/mocha": "^10.0.8",
     "@types/node": "^22.7.5",
-    "@types/uuid": "^10.0.0",
     "axios-mock-adapter": "^2.0.0",
     "eslint": "^9.15.0",
     "globals": "^15.12.0",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.4",
-    "typescript": "^4.4.3",
+    "typescript": "^5.6.3",
     "typescript-eslint": "^8.15.0",
     "webpack": "^5.52.0",
     "webpack-cli": "^4.8.0"

package/src/__tests__/chirpier.test.ts

@@ -1,192 +1,396 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
 import {
-  Chirpier,
+  Client,
   ChirpierError,
-  Event,
+  Log,
   LogLevel,
+  createClient,
+  flush,
   initialize,
-  monitor,
+  logEvent,
+  stop,
 } from "../index";
 import {
   DEFAULT_API_ENDPOINT,
-  DEFAULT_RETRIES,
-  DEFAULT_TIMEOUT,
-  DEFAULT_BATCH_SIZE,
-  DEFAULT_FLUSH_DELAY,
 } from "../constants";
-import MockAdapter from "axios-mock-adapter";
-import axios from "axios";
 
 describe("Chirpier SDK", () => {
+  afterEach(async () => {
+    await stop();
+  });
+
   describe("Initialization", () => {
-    test("should throw error if monitor is called before initialize", () => {
-      const event: Event = {
-        group_id: "bfd9299d-817a-452f-bc53-6e154f2281fc",
-        stream_name: "test-stream",
+    test("should throw error if logEvent is called before initialize", async () => {
+      const log: Log = {
+        event: "test-event",
         value: 1,
       };
 
-      expect(() => monitor(event)).toThrow(ChirpierError);
-      expect(() => monitor(event)).toThrow(
+      await expect(logEvent(log)).rejects.toThrow(ChirpierError);
+      await expect(logEvent(log)).rejects.toThrow(
         "Chirpier SDK is not initialized. Please call initialize() first."
       );
     });
 
-    test("should initialize with default values", () => {
+    test("should initialize with default values", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
+
       initialize({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+        key: "chp_test_default_key",
         logLevel: LogLevel.None,
       });
-      const chirpier = Chirpier.getInstance({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
-      });
 
-      // Setup mock server
+      await logEvent({ event: "sdk.initialized", value: 1 });
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      expect(mock.history.post[0].url).toBe(DEFAULT_API_ENDPOINT);
+    });
+
+    test("should initialize with custom apiEndpoint", async () => {
+      const customEndpoint = "https://localhost:3001/v1.0/logs";
       const mock = new MockAdapter(axios);
-      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
+      mock.onPost(customEndpoint).reply(200, { success: true });
 
-      expect(chirpier?.["apiEndpoint"]).toBe(DEFAULT_API_ENDPOINT);
-      expect(chirpier?.["retries"]).toBe(DEFAULT_RETRIES);
-      expect(chirpier?.["timeout"]).toBe(DEFAULT_TIMEOUT);
-      expect(chirpier?.["batchSize"]).toBe(DEFAULT_BATCH_SIZE);
-      expect(chirpier?.["flushDelay"]).toBe(DEFAULT_FLUSH_DELAY);
+      initialize({
+        key: "chp_test_custom_endpoint",
+        apiEndpoint: customEndpoint,
+        logLevel: LogLevel.None,
+      });
 
-      Chirpier.stop();
+      await logEvent({ event: "sdk.custom-endpoint", value: 1 });
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      expect(mock.history.post[0].url).toBe(customEndpoint);
     });
 
-    test("should throw error if key is not provided", () => {
+    test("should throw error for invalid apiEndpoint", () => {
       expect(() => {
         initialize({
-          key: "api_key",
-          logLevel: LogLevel.None,
+          key: "chp_test_invalid_endpoint",
+          apiEndpoint: "not-a-url",
         });
-      }).toThrow(ChirpierError);
+      }).toThrow("apiEndpoint must be a valid absolute URL");
+    });
+
+    test("should throw error for invalid key prefix", () => {
       expect(() => {
         initialize({
-          key: "api_key",
+          key: "invalid_key",
           logLevel: LogLevel.None,
         });
-      }).toThrow("Invalid API key: Not a valid JWT");
+      }).toThrow("Invalid API key: must start with 'chp_'");
+    });
+
+    test("should load key from process environment", () => {
+      const previousKey = process.env.CHIRPIER_API_KEY;
+      process.env.CHIRPIER_API_KEY = "chp_env_key";
+
+      try {
+        initialize({ logLevel: LogLevel.None });
+        expect(() => initialize({ logLevel: LogLevel.None })).not.toThrow();
+      } finally {
+        if (previousKey === undefined) {
+          delete process.env.CHIRPIER_API_KEY;
+        } else {
+          process.env.CHIRPIER_API_KEY = previousKey;
+        }
+      }
+    });
+
+    test("should load key from .env fallback", () => {
+      const previousKey = process.env.CHIRPIER_API_KEY;
+      const previousCwd = process.cwd();
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "chirpier-js-"));
+
+      try {
+        delete process.env.CHIRPIER_API_KEY;
+        fs.writeFileSync(path.join(tempDir, ".env"), "CHIRPIER_API_KEY=chp_dotenv_key\n");
+        process.chdir(tempDir);
+
+        initialize({ logLevel: LogLevel.None });
+        expect(() => initialize({ logLevel: LogLevel.None })).not.toThrow();
+      } finally {
+        process.chdir(previousCwd);
+        if (previousKey === undefined) {
+          delete process.env.CHIRPIER_API_KEY;
+        } else {
+          process.env.CHIRPIER_API_KEY = previousKey;
+        }
+      }
     });
   });
 
-  describe("monitor", () => {
-    test("event should be sent", async () => {
-      // Setup mock server
+  describe("logEvent", () => {
+    test("log should be sent", async () => {
       const mock = new MockAdapter(axios);
       mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
       initialize({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+        key: "chp_log_send_key",
         logLevel: LogLevel.None,
       });
 
-      const event: Event = {
-        group_id: "bfd9299d-817a-452f-bc53-6e154f2281fc",
-        stream_name: "test-stream",
+      const log: Log = {
+        agent: "api.worker",
+        event: "request.finished",
         value: 1,
       };
 
-      monitor(event);
-
-      await new Promise((resolve) => setTimeout(resolve, 2000)); // Wait for flush
+      await logEvent(log);
+      await new Promise((resolve) => setTimeout(resolve, 2000));
 
       expect(mock.history.post.length).toBe(1);
       expect(mock.history.post[0].url).toBe(DEFAULT_API_ENDPOINT);
       expect(JSON.parse(mock.history.post[0].data)).toEqual([
         {
-          group_id: "bfd9299d-817a-452f-bc53-6e154f2281fc",
-          stream_name: "test-stream",
+          log_id: expect.any(String),
+          agent: "api.worker",
+          event: "request.finished",
           value: 1,
         },
       ]);
+      expect(JSON.parse(mock.history.post[0].data)[0].log_id).toMatch(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+      );
+    });
 
-      // Clean up the mock
-      mock.reset();
-      Chirpier.stop();
+    test("should preserve provided log_id", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
+
+      initialize({
+        key: "chp_log_id_key",
+        logLevel: LogLevel.None,
+      });
+
+      await logEvent({
+        log_id: "9f97d65f-fb30-4062-b4d0-8617c03fe4f6",
+        event: "request.finished",
+        value: 1,
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const payload = JSON.parse(mock.history.post[0].data);
+      expect(payload[0].log_id).toBe("9f97d65f-fb30-4062-b4d0-8617c03fe4f6");
     });
 
-    test("should silently drop invalid event", async () => {
+    test("agent whitespace should be omitted", async () => {
       const mock = new MockAdapter(axios);
       mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
       initialize({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
-        logLevel: LogLevel.Debug,
+        key: "chp_log_whitespace_agent",
+        logLevel: LogLevel.None,
       });
 
-      const invalidEvent = {
-        group_id: "invalid-uuid",
-        stream_name: "",
-        value: 0,
-      } as Event;
+      await logEvent({
+        agent: "   ",
+        event: "metric.tick",
+        value: 42,
+      });
 
-      const consoleSpy = jest.spyOn(console, "debug");
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const payload = JSON.parse(mock.history.post[0].data);
+      expect(payload[0].agent).toBeUndefined();
+    });
 
-      await monitor(invalidEvent);
+    test("should support meta payload", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
-      expect(consoleSpy).toHaveBeenCalledWith(
-        "Invalid event format, dropping event:",
-        invalidEvent
-      );
-      expect(mock.history.post.length).toBe(0); // No request should be made
+      initialize({
+        key: "chp_log_meta_key",
+        logLevel: LogLevel.None,
+      });
+
+      await logEvent({
+        agent: "api.worker",
+        event: "request.finished",
+        value: 200,
+        meta: {
+          path: "/v1.0/logs",
+          status: "ok",
+        },
+      });
 
-      // Clean up
-      mock.reset();
-      consoleSpy.mockRestore();
-      Chirpier.stop();
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const payload = JSON.parse(mock.history.post[0].data);
+      expect(payload[0].meta.path).toBe("/v1.0/logs");
     });
 
-    test("should batch events and flush when batch size is reached", async () => {
+    test("should support occurred_at timestamp", async () => {
       const mock = new MockAdapter(axios);
       mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
       initialize({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+        key: "chp_log_occurred_at_key",
         logLevel: LogLevel.None,
       });
 
-      const event: Event = {
-        group_id: "bfd9299d-817a-452f-bc53-6e154f2281fc",
-        stream_name: "test-stream",
+      const occurredAt = new Date(Date.now() - 2 * 60 * 60 * 1000);
+
+      await logEvent({
+        event: "request.finished",
         value: 1,
-      };
+        occurred_at: occurredAt,
+      });
 
-      monitor(event);
-      monitor(event);
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      const payload = JSON.parse(mock.history.post[0].data);
+      expect(payload[0].occurred_at).toBe(occurredAt.toISOString());
+    });
 
-      await new Promise((resolve) => setTimeout(resolve, 2000)); // Wait for flush
+    test("should throw error for invalid log", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
-      expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data).length).toBe(2);
+      initialize({
+        key: "chp_invalid_log_key",
+        logLevel: LogLevel.Debug,
+      });
+
+      await expect(
+        logEvent({
+          event: "",
+          value: 0,
+        })
+      ).rejects.toThrow(ChirpierError);
 
-      mock.reset();
-      Chirpier.stop();
+      await expect(
+        logEvent({
+          event: "too-old",
+          value: 1,
+          occurred_at: new Date(Date.now() - 31 * 24 * 60 * 60 * 1000),
+        })
+      ).rejects.toThrow(ChirpierError);
+
+      await expect(
+        logEvent({
+          event: "too-future",
+          value: 1,
+          occurred_at: new Date(Date.now() + 25 * 60 * 60 * 1000),
+        })
+      ).rejects.toThrow(ChirpierError);
+
+      await expect(
+        logEvent({
+          log_id: "not-a-uuid",
+          event: "bad-log-id",
+          value: 1,
+        })
+      ).rejects.toThrow(ChirpierError);
+
+      expect(mock.history.post.length).toBe(0);
     });
 
-    test("should flush events after interval", async () => {
+    test("should batch logs and flush when batch size is reached", async () => {
       const mock = new MockAdapter(axios);
       mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
 
       initialize({
-        key: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+        key: "chp_batch_key",
         logLevel: LogLevel.None,
       });
 
-      const event: Event = {
-        group_id: "bfd9299d-817a-452f-bc53-6e154f2281fc",
-        stream_name: "test-stream",
+      await logEvent({ event: "batch.event", value: 1 });
+      await logEvent({ event: "batch.event", value: 2 });
+
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      expect(mock.history.post.length).toBe(1);
+      expect(JSON.parse(mock.history.post[0].data).length).toBe(2);
+    });
+  });
+
+  describe("Client API", () => {
+    test("createClient supports direct logging", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
+
+      const client: Client = createClient({ key: "chp_direct_client_key" });
+      await client.log({
+        event: "direct.client.log",
         value: 1,
-      };
+      });
 
-      monitor(event);
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      expect(mock.history.post.length).toBe(1);
+      expect(JSON.parse(mock.history.post[0].data)[0].event).toBe("direct.client.log");
+
+      await client.shutdown();
+    });
 
-      await new Promise((resolve) => setTimeout(resolve, 2000)); // Wait for flush
+    test("flush should force delivery of queued logs", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost(DEFAULT_API_ENDPOINT).reply(200, { success: true });
+
+      initialize({
+        key: "chp_flush_key",
+        logLevel: LogLevel.None,
+        flushDelay: 10000,
+      });
 
+      await logEvent({ event: "queued.before.flush", value: 1 });
+      expect(mock.history.post.length).toBe(0);
+
+      await flush();
       expect(mock.history.post.length).toBe(1);
-      expect(JSON.parse(mock.history.post[0].data).length).toBe(1);
+      expect(JSON.parse(mock.history.post[0].data)[0].event).toBe("queued.before.flush");
+    });
+
+    test("getEventLogs uses servicer endpoint with period, limit, and offset", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onGet("https://api.chirpier.co/v1.0/events/evt_123/logs?period=hour&limit=25&offset=10").reply(200, []);
+
+      const client: Client = createClient({ key: "chp_client_logs_key" });
+      try {
+        await client.getEventLogs("evt_123", { period: "hour", limit: 25, offset: 10 });
+        expect(mock.history.get[0].url).toBe("https://api.chirpier.co/v1.0/events/evt_123/logs?period=hour&limit=25&offset=10");
+      } finally {
+        await client.shutdown();
+      }
+    });
+
+    test("getAlertDeliveries uses pagination params", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onGet("https://api.chirpier.co/v1.0/alerts/alrt_123/deliveries?kind=test&limit=20&offset=5").reply(200, []);
+
+      const client: Client = createClient({ key: "chp_client_alert_key" });
+      try {
+        await client.getAlertDeliveries("alrt_123", { kind: "test", limit: 20, offset: 5 });
+        expect(mock.history.get[0].url).toBe("https://api.chirpier.co/v1.0/alerts/alrt_123/deliveries?kind=test&limit=20&offset=5");
+      } finally {
+        await client.shutdown();
+      }
+    });
+
+    test("archiveAlert posts to servicer endpoint", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost("https://api.chirpier.co/v1.0/alerts/alrt_123/archive").reply(200, {});
+
+      const client: Client = createClient({ key: "chp_client_alert_key" });
+      try {
+        await client.archiveAlert("alrt_123");
+        expect(mock.history.post[0].url).toBe("https://api.chirpier.co/v1.0/alerts/alrt_123/archive");
+      } finally {
+        await client.shutdown();
+      }
+    });
 
-      mock.reset();
-      Chirpier.stop();
+    test("testWebhook posts to servicer endpoint", async () => {
+      const mock = new MockAdapter(axios);
+      mock.onPost("https://api.chirpier.co/v1.0/webhooks/whk_123/test").reply(200);
+
+      const client: Client = createClient({ key: "chp_client_webhook_key" });
+      try {
+        await client.testWebhook("whk_123");
+        expect(mock.history.post[0].url).toBe("https://api.chirpier.co/v1.0/webhooks/whk_123/test");
+      } finally {
+        await client.shutdown();
+      }
     });
   });
 });

package/src/constants.ts

@@ -1,8 +1,9 @@
 // constants.ts
 
-export const DEFAULT_RETRIES = 15;
-export const DEFAULT_TIMEOUT = 5000
-export const DEFAULT_BATCH_SIZE = 350;
-export const DEFAULT_FLUSH_DELAY = 500;
-export const MAX_QUEUE_SIZE = 50000;
-export const DEFAULT_API_ENDPOINT = "https://eu-west.chirpier.co/v1.0/events"
+export const DEFAULT_RETRIES = 15 as const;
+export const DEFAULT_TIMEOUT = 5000 as const;
+export const DEFAULT_BATCH_SIZE = 500 as const;
+export const DEFAULT_FLUSH_DELAY = 500 as const;
+export const MAX_QUEUE_SIZE = 5000 as const;
+export const DEFAULT_API_ENDPOINT = "https://logs.chirpier.co/v1.0/logs" as const;
+export const DEFAULT_SERVICER_ENDPOINT = "https://api.chirpier.co/v1.0" as const;