seqpulse 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,9 @@
 # seqpulse (Node.js SDK)
 
-SeqPulse SDK for:
+SeqPulse Node SDK couvre deux usages:
 
-- HTTP metrics instrumentation
-- metrics endpoint exposure
-- optional HMAC v2 validation on inbound SeqPulse calls
+- Runtime application: instrumentation HTTP + endpoint metrics + validation HMAC v2
+- CI/CD integration: client `trigger/finish` pour orchestrer un deployment SeqPulse
 
 ## Install
 
@@ -14,7 +13,7 @@ npm install seqpulse
 pnpm add seqpulse
 ```
 
-## Express usage
+## Runtime (Express)
 
 ```js
 const express = require("express");
@@ -37,8 +36,6 @@ app.listen(3000, () => {
 });
 ```
 
-## Returned payload
-
 `GET /seqpulse-metrics` returns:
 
 ```json
@@ -53,11 +50,50 @@ app.listen(3000, () => {
 }
 ```
 
-## Notes
+## CI/CD client (trigger/finish)
+
+```js
+const seqpulse = require("seqpulse");
+
+const client = seqpulse.createCIClient({
+  baseUrl: process.env.SEQPULSE_BASE_URL,
+  apiKey: process.env.SEQPULSE_API_KEY,
+  metricsEndpoint: process.env.SEQPULSE_METRICS_ENDPOINT,
+  env: "prod",
+  nonBlocking: true,
+});
+
+async function runDeployment() {
+  const trigger = await client.trigger({
+    branch: process.env.GITHUB_REF_NAME,
+    idempotencyKey: `gha-${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT}`,
+  });
+
+  // Deploy your app here...
+  const deploySucceeded = true;
+
+  if (trigger.ok && trigger.deploymentId) {
+    await client.finish({
+      deploymentId: trigger.deploymentId,
+      result: deploySucceeded ? "success" : "failed",
+    });
+  }
+}
+```
+
+### CI behavior
+
+- `nonBlocking: true` (default): returns a skipped/error result instead of throwing.
+- `nonBlocking: false`: throws on API/config errors.
+- idempotency key helper available: `seqpulse.buildCiIdempotencyKey()`.
+
+## Compatibility note
+
+Cette evolution **n'ecrase pas** le SDK runtime actuel:
 
-- This SDK does not manage CI/CD trigger/finish workflow.
-- `apiKey` is optional and not used directly in metrics payload or HMAC validation.
-- Metrics sampling window is fixed to 60 seconds (not configurable in SDK init).
+- l'endpoint `/seqpulse-metrics` reste le meme
+- la logique HMAC runtime reste la meme
+- le client CI est ajoute en couche supplementaire
 
 ## Local smoke test
 

package/index.d.ts

@@ -15,10 +15,96 @@ export type SeqPulseMetrics = {
   memory_usage: number
 }
 
+export type SeqPulseCiTransportRequest = {
+  url: string
+  headers: Record<string, string>
+  body: string
+  timeoutMs: number
+}
+
+export type SeqPulseCiTransportResponse = {
+  status: number
+  text: string
+}
+
+export type SeqPulseCiTransport = (
+  request: SeqPulseCiTransportRequest
+) => Promise<SeqPulseCiTransportResponse>
+
+export type SeqPulseCiConfig = {
+  baseUrl?: string
+  apiKey?: string
+  metricsEndpoint?: string
+  env?: string
+  timeoutMs?: number
+  nonBlocking?: boolean
+  transport?: SeqPulseCiTransport
+}
+
+export type SeqPulseTriggerOptions = SeqPulseCiConfig & {
+  env?: string
+  idempotencyKey?: string
+  branch?: string
+}
+
+export type SeqPulseFinishOptions = SeqPulseCiConfig & {
+  deploymentId?: string
+  result?: "success" | "failed" | string
+  pipelineStatus?: string
+  jobStatus?: string
+}
+
+export type SeqPulseCiSuccess = {
+  ok: true
+  skipped: false
+  action: "trigger" | "finish"
+  httpStatus: number
+  status?: string
+  message?: string | null
+  data: Record<string, any>
+}
+
+export type SeqPulseTriggerSuccess = SeqPulseCiSuccess & {
+  action: "trigger"
+  deploymentId: string
+  status: string
+}
+
+export type SeqPulseCiError = {
+  ok: false
+  skipped: true
+  action: string
+  httpStatus: number
+  error: string
+  responseText: string
+}
+
+export type SeqPulseCiResult = SeqPulseCiSuccess | SeqPulseCiError
+export type SeqPulseTriggerResult = SeqPulseTriggerSuccess | SeqPulseCiError
+
+export type SeqPulseCiClient = {
+  trigger(options?: SeqPulseTriggerOptions): Promise<SeqPulseTriggerResult>
+  finish(options: SeqPulseFinishOptions): Promise<SeqPulseCiResult>
+}
+
 export type SeqPulseInstance = {
   init(config: SeqPulseInitConfig): void
   metrics(): (req: any, res: any, next: () => void) => void
   getMetricsSnapshot(): SeqPulseMetrics
+
+  createCIClient(config?: SeqPulseCiConfig): SeqPulseCiClient
+  triggerDeployment(options?: SeqPulseTriggerOptions): Promise<SeqPulseTriggerResult>
+  finishDeployment(options: SeqPulseFinishOptions): Promise<SeqPulseCiResult>
+  buildCiIdempotencyKey(): string
+  inferResultFromPipelineStatus(status?: string): "success" | "failed"
+
+  ci: {
+    createClient(config?: SeqPulseCiConfig): SeqPulseCiClient
+    trigger(options?: SeqPulseTriggerOptions): Promise<SeqPulseTriggerResult>
+    finish(options: SeqPulseFinishOptions): Promise<SeqPulseCiResult>
+    buildIdempotencyKey(): string
+    inferResultFromPipelineStatus(status?: string): "success" | "failed"
+  }
 }
 
 declare const seqpulse: SeqPulseInstance

package/index.js

@@ -3,17 +3,17 @@
 const crypto = require("node:crypto");
 const os = require("node:os");
 
-const DEFAULT_WINDOW_SECONDS = 60;
+const SAMPLE_WINDOW_SECONDS = 60;
 const DEFAULT_ENDPOINT = "/seqpulse-metrics";
 const DEFAULT_MAX_SKEW_PAST_SECONDS = 300;
 const DEFAULT_MAX_SKEW_FUTURE_SECONDS = 30;
+const DEFAULT_CI_TIMEOUT_MS = 4000;
 
 const state = {
   initialized: false,
   config: {
     apiKey: "",
     endpoint: DEFAULT_ENDPOINT,
-    windowSeconds: DEFAULT_WINDOW_SECONDS,
     hmacEnabled: false,
     hmacSecret: "",
     maxSkewPastSeconds: DEFAULT_MAX_SKEW_PAST_SECONDS,
@@ -31,6 +31,11 @@ function canonicalizePath(path) {
   return normalized;
 }
 
+function normalizeBaseUrl(baseUrl) {
+  if (!baseUrl) return "";
+  return String(baseUrl).replace(/\/+$/, "");
+}
+
 function nowMs() {
   return Date.now();
 }
@@ -48,7 +53,7 @@ function round(value, digits) {
 }
 
 function cleanupOldSamples() {
-  const cutoff = nowMs() - state.config.windowSeconds * 1000;
+  const cutoff = nowMs() - SAMPLE_WINDOW_SECONDS * 1000;
   state.samples = state.samples.filter((item) => item.atMs >= cutoff);
 }
 
@@ -123,7 +128,6 @@ function validateHmacRequest(req, res) {
 function getMetricsSnapshot() {
   cleanupOldSamples();
   const sampleCount = state.samples.length;
-  const windowSeconds = state.config.windowSeconds;
   const totalErrors = state.samples.reduce((acc, item) => acc + (item.isError ? 1 : 0), 0);
   const latencies = state.samples.map((item) => item.latencyMs);
 
@@ -131,7 +135,7 @@ function getMetricsSnapshot() {
   const memoryUsageRaw = os.totalmem() > 0 ? process.memoryUsage().rss / os.totalmem() : 0;
 
   return {
-    requests_per_sec: round(sampleCount / windowSeconds, 3),
+    requests_per_sec: round(sampleCount / SAMPLE_WINDOW_SECONDS, 3),
     latency_p95: round(percentile95(latencies), 3),
     error_rate: sampleCount > 0 ? round(totalErrors / sampleCount, 6) : 0,
     cpu_usage: round(Math.min(Math.max(cpuUsageRaw, 0), 1), 6),
@@ -154,10 +158,7 @@ function init(config) {
 
   state.config = {
     apiKey: typeof config.apiKey === "string" ? config.apiKey : "",
-    endpoint,
-    // Fixed to backend contract: 60s observation window for SDK sampling.
-    windowSeconds: DEFAULT_WINDOW_SECONDS,
-    hmacEnabled,
+    endpoint,    hmacEnabled,
     hmacSecret,
     maxSkewPastSeconds: Number(config.maxSkewPastSeconds || DEFAULT_MAX_SKEW_PAST_SECONDS),
     maxSkewFutureSeconds: Number(config.maxSkewFutureSeconds || DEFAULT_MAX_SKEW_FUTURE_SECONDS),
@@ -194,8 +195,284 @@ function metrics() {
   };
 }
 
+function safeJsonParse(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function inferResultFromPipelineStatus(status) {
+  const normalized = String(status || "").toLowerCase().trim();
+  if (["success", "ok", "passed", "pass"].includes(normalized)) return "success";
+  return "failed";
+}
+
+function buildCiIdempotencyKey() {
+  if (process.env.GITHUB_RUN_ID) {
+    return `gha-${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT || "1"}`;
+  }
+  if (process.env.CI_PIPELINE_ID) {
+    return `gl-${process.env.CI_PIPELINE_ID}-${process.env.CI_PIPELINE_IID || "1"}`;
+  }
+  if (process.env.CIRCLE_WORKFLOW_ID) {
+    return `circle-${process.env.CIRCLE_WORKFLOW_ID}-${process.env.CIRCLE_BUILD_NUM || "1"}`;
+  }
+  if (process.env.BUILD_ID || process.env.BUILD_TAG) {
+    return `jenkins-${process.env.BUILD_TAG || process.env.BUILD_ID}`;
+  }
+  return `seqpulse-${nowMs()}`;
+}
+
+function inferBranchName() {
+  return (
+    process.env.GITHUB_REF_NAME ||
+    process.env.CI_COMMIT_REF_NAME ||
+    process.env.CIRCLE_BRANCH ||
+    process.env.BRANCH_NAME ||
+    "unknown"
+  );
+}
+
+async function defaultCiTransport({ url, headers, body, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal,
+    });
+    return {
+      status: response.status,
+      text: await response.text(),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function createErrorResult({ action, error, nonBlocking, httpStatus = 0, responseText = "" }) {
+  const message = `${action} failed: ${error}`;
+  if (!nonBlocking) {
+    throw new Error(message);
+  }
+  return {
+    ok: false,
+    skipped: true,
+    action,
+    httpStatus,
+    error: String(error),
+    responseText,
+  };
+}
+
+function createCIClient(config = {}) {
+  const defaults = {
+    baseUrl: normalizeBaseUrl(config.baseUrl || process.env.SEQPULSE_BASE_URL || ""),
+    apiKey: String(config.apiKey || process.env.SEQPULSE_API_KEY || ""),
+    metricsEndpoint: String(config.metricsEndpoint || process.env.SEQPULSE_METRICS_ENDPOINT || ""),
+    env: String(config.env || "prod"),
+    timeoutMs: Number(config.timeoutMs || DEFAULT_CI_TIMEOUT_MS),
+    nonBlocking: config.nonBlocking !== false,
+    transport: typeof config.transport === "function" ? config.transport : defaultCiTransport,
+  };
+
+  async function request(path, payload, options = {}) {
+    const action = options.action || path;
+    const nonBlocking = options.nonBlocking !== undefined ? options.nonBlocking : defaults.nonBlocking;
+    const baseUrl = normalizeBaseUrl(options.baseUrl || defaults.baseUrl);
+    const apiKey = String(options.apiKey || defaults.apiKey || "");
+    const timeoutMs = Number(options.timeoutMs || defaults.timeoutMs);
+
+    if (!baseUrl || !apiKey) {
+      return createErrorResult({
+        action,
+        nonBlocking,
+        error: "missing baseUrl/apiKey",
+      });
+    }
+
+    const url = `${baseUrl}${path}`;
+    const body = JSON.stringify(payload);
+
+    let transportResponse;
+    try {
+      transportResponse = await defaults.transport({
+        url,
+        headers: {
+          "X-API-Key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body,
+        timeoutMs,
+      });
+    } catch (error) {
+      return createErrorResult({
+        action,
+        nonBlocking,
+        error: error && error.message ? error.message : String(error),
+      });
+    }
+
+    const httpStatus = Number(transportResponse && transportResponse.status ? transportResponse.status : 0);
+    const responseText = (transportResponse && transportResponse.text) || "";
+    const data = safeJsonParse(responseText);
+
+    if (!httpStatus) {
+      return createErrorResult({
+        action,
+        nonBlocking,
+        error: "unreachable",
+        httpStatus: 0,
+        responseText,
+      });
+    }
+
+    if (httpStatus >= 400) {
+      return createErrorResult({
+        action,
+        nonBlocking,
+        error: `http ${httpStatus}`,
+        httpStatus,
+        responseText,
+      });
+    }
+
+    return {
+      ok: true,
+      skipped: false,
+      action,
+      httpStatus,
+      data: data || {},
+      responseText,
+    };
+  }
+
+  async function trigger(options = {}) {
+    const nonBlocking = options.nonBlocking !== undefined ? options.nonBlocking : defaults.nonBlocking;
+    const metricsEndpoint = String(options.metricsEndpoint || defaults.metricsEndpoint || "");
+
+    if (!metricsEndpoint) {
+      return createErrorResult({
+        action: "trigger",
+        nonBlocking,
+        error: "missing metricsEndpoint",
+      });
+    }
+
+    const payload = {
+      env: String(options.env || defaults.env || "prod"),
+      metrics_endpoint: metricsEndpoint,
+      idempotency_key: String(options.idempotencyKey || buildCiIdempotencyKey()),
+      branch: String(options.branch || inferBranchName()),
+    };
+
+    const result = await request("/deployments/trigger", payload, {
+      ...options,
+      action: "trigger",
+      nonBlocking,
+    });
+    if (!result.ok) return result;
+
+    const deploymentId = result.data && result.data.deployment_id ? String(result.data.deployment_id) : "";
+    if (!deploymentId) {
+      return createErrorResult({
+        action: "trigger",
+        nonBlocking,
+        error: "missing deployment_id in response",
+        httpStatus: result.httpStatus,
+        responseText: result.responseText,
+      });
+    }
+
+    return {
+      ok: true,
+      skipped: false,
+      action: "trigger",
+      httpStatus: result.httpStatus,
+      deploymentId,
+      status: String(result.data.status || "created"),
+      message: result.data.message || null,
+      data: result.data,
+    };
+  }
+
+  async function finish(options = {}) {
+    const nonBlocking = options.nonBlocking !== undefined ? options.nonBlocking : defaults.nonBlocking;
+    const deploymentId = String(options.deploymentId || "");
+    if (!deploymentId) {
+      return createErrorResult({
+        action: "finish",
+        nonBlocking,
+        error: "missing deploymentId",
+      });
+    }
+
+    const resultValue = String(
+      options.result || inferResultFromPipelineStatus(options.pipelineStatus || options.jobStatus || "success")
+    );
+    const metricsEndpoint = String(options.metricsEndpoint || defaults.metricsEndpoint || "");
+
+    const payload = {
+      deployment_id: deploymentId,
+      result: resultValue,
+    };
+    if (metricsEndpoint) {
+      payload.metrics_endpoint = metricsEndpoint;
+    }
+
+    const result = await request("/deployments/finish", payload, {
+      ...options,
+      action: "finish",
+      nonBlocking,
+    });
+    if (!result.ok) return result;
+
+    return {
+      ok: true,
+      skipped: false,
+      action: "finish",
+      httpStatus: result.httpStatus,
+      status: String(result.data.status || "accepted"),
+      message: result.data.message || null,
+      data: result.data,
+    };
+  }
+
+  return {
+    trigger,
+    finish,
+  };
+}
+
+async function triggerDeployment(options = {}) {
+  const client = createCIClient(options);
+  return client.trigger(options);
+}
+
+async function finishDeployment(options = {}) {
+  const client = createCIClient(options);
+  return client.finish(options);
+}
+
 module.exports = {
   init,
   metrics,
   getMetricsSnapshot,
+  createCIClient,
+  triggerDeployment,
+  finishDeployment,
+  buildCiIdempotencyKey,
+  inferResultFromPipelineStatus,
+  ci: {
+    createClient: createCIClient,
+    trigger: triggerDeployment,
+    finish: finishDeployment,
+    buildIdempotencyKey: buildCiIdempotencyKey,
+    inferResultFromPipelineStatus,
+  },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seqpulse",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SeqPulse SDK for metrics endpoint instrumentation and HMAC validation",
   "main": "index.js",
   "types": "index.d.ts",

package/scripts/smoke.js

@@ -98,9 +98,71 @@ async function testHmac() {
   }
 }
 
+async function testCiClient() {
+  const calls = [];
+  const transport = async ({ url, body }) => {
+    calls.push({ url, body: JSON.parse(body) });
+    if (url.endsWith("/deployments/trigger")) {
+      return {
+        status: 200,
+        text: JSON.stringify({
+          deployment_id: "00000000-0000-0000-0000-000000000123",
+          status: "created",
+          message: "Deployment created",
+        }),
+      };
+    }
+    if (url.endsWith("/deployments/finish")) {
+      return {
+        status: 200,
+        text: JSON.stringify({
+          status: "accepted",
+          message: "Deployment finished",
+        }),
+      };
+    }
+    return { status: 404, text: "" };
+  };
+
+  const client = sdk.createCIClient({
+    baseUrl: "https://api.seqpulse.dev",
+    apiKey: "sp_test",
+    metricsEndpoint: "https://my-app.example.com/seqpulse-metrics",
+    transport,
+  });
+
+  const triggerResult = await client.trigger({
+    idempotencyKey: "smoke-run-1",
+    branch: "main",
+    env: "prod",
+  });
+  if (!triggerResult.ok || !triggerResult.deploymentId) {
+    throw new Error("CI trigger should return a deployment id");
+  }
+
+  const finishResult = await client.finish({
+    deploymentId: triggerResult.deploymentId,
+    pipelineStatus: "success",
+  });
+  if (!finishResult.ok || finishResult.status !== "accepted") {
+    throw new Error("CI finish should be accepted");
+  }
+
+  if (calls.length !== 2) {
+    throw new Error("CI smoke should execute trigger + finish calls");
+  }
+
+  const nonBlockingClient = sdk.createCIClient({ nonBlocking: true, transport });
+  const skipped = await nonBlockingClient.trigger({ idempotencyKey: "x" });
+  if (skipped.ok !== false || skipped.skipped !== true) {
+    throw new Error("Non-blocking trigger should skip when config is missing");
+  }
+}
+
 async function main() {
   await testNoHmac();
   await testHmac();
+  await testCiClient();
   console.log("seqpulse node smoke: OK");
 }