@kivia/sdk 0.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: release
+
+on:
+    push:
+        tags:
+            - "v*"
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            id-token: write
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: "22"
+                  registry-url: "https://registry.npmjs.org"
+            - run: npm ci
+            - run: npm run build
+            - run: npm publish --provenance --access public
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                  generate_release_notes: true

package/README.md

@@ -0,0 +1,78 @@
+# Kivia TypeScript SDK
+
+The Kivia TypeScript SDK is the official Node.js client for the Kivia observability platform. It allows Node.js developers using Express or Fastify to instantly track API request metrics, response times, and paths.
+
+## Installation
+
+```bash
+npm install @kivia/sdk
+```
+
+## Quick Start (with Express)
+
+```typescript
+import express from 'express';
+import { KiviaClient } from '@kivia/sdk';
+
+const app = express();
+
+const kiviaClient = new KiviaClient({
+  apiKey: 'YOUR_KIVIA_API_KEY',
+});
+
+// Let Kivia track all your network traffic by setting this global middleware
+app.use(kiviaClient.logMiddleware());
+
+app.get('/hello', (req, res) => {
+  res.send('Hello from Kivia TS SDK!');
+});
+
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+## Quick Start (with NestJS)
+
+Because NestJS runs on Express (or Fastify) under the hood, you can simply inject the SDK as a global middleware right in your `main.ts` bootstrap function!
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { KiviaClient } from '@kivia/sdk';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const kiviaClient = new KiviaClient({
+    apiKey: 'YOUR_KIVIA_API_KEY'
+  });
+
+  // Just apply it as global middleware!
+  app.use(kiviaClient.logMiddleware());
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## Quick Start (with Fastify Plugin)
+
+We export a native Fastify plugin so you can easily encapsulate options and registration.
+
+```typescript
+import Fastify from 'fastify';
+import { kiviaFastifyPlugin } from '@kivia/sdk';
+
+const fastify = Fastify({ logger: false });
+
+// Register as a native Fastify plugin
+fastify.register(kiviaFastifyPlugin, {
+  apiKey: 'YOUR_KIVIA_API_KEY'
+});
+
+fastify.get('/hello', async (request, reply) => {
+  return { message: 'Hello from Kivia TS SDK using Fastify Plugin!' };
+});
+
+fastify.listen({ port: 3000 });
+```

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import { DynoClientOptions } from './types';
+export declare class DynoClient {
+    private apiKey;
+    private baseUrl;
+    constructor(options: DynoClientOptions);
+    /**
+     * Express/Connect middleware for automatically logging requests.
+     */
+    logMiddleware(): (req: any, res: any, next: any) => void;
+    /**
+     * Fastify hook variant to be used with the 'onResponse' lifecycle hook.
+     * Usage: fastify.addHook('onResponse', dynoClient.logFastifyOnResponse());
+     */
+    logFastifyOnResponse(): (request: any, reply: any) => Promise<void>;
+    private sendLog;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAO,MAAM,SAAS,CAAC;AAEjD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,iBAAiB;IAKtC;;OAEG;IACI,aAAa,KACV,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG;IAsBvC;;;OAGG;IACI,oBAAoB,KACX,SAAS,GAAG,EAAE,OAAO,GAAG;YAgB1B,OAAO;CAmBtB"}

package/dist/client.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynoClient = void 0;
+class DynoClient {
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl || 'https://nginx-production-a9aa.up.railway.app/api/v1';
+    }
+    /**
+     * Express/Connect middleware for automatically logging requests.
+     */
+    logMiddleware() {
+        return (req, res, next) => {
+            const start = Date.now();
+            // Listen for the response to finish
+            res.on('finish', () => {
+                var _a;
+                const latency = Date.now() - start;
+                const logEntry = {
+                    path: req.originalUrl || req.url,
+                    status: res.statusCode,
+                    ip_address: req.ip || ((_a = req.connection) === null || _a === void 0 ? void 0 : _a.remoteAddress),
+                    timestamp: new Date().toISOString(),
+                    latency,
+                };
+                this.sendLog(logEntry);
+            });
+            next();
+        };
+    }
+    /**
+     * Fastify hook variant to be used with the 'onResponse' lifecycle hook.
+     * Usage: fastify.addHook('onResponse', dynoClient.logFastifyOnResponse());
+     */
+    logFastifyOnResponse() {
+        return async (request, reply) => {
+            var _a, _b, _c, _d;
+            // reply.getResponseTime() is available in Fastify to get latency in ms
+            const latency = reply.getResponseTime ? reply.getResponseTime() : 0;
+            const logEntry = {
+                path: request.url || ((_a = request.raw) === null || _a === void 0 ? void 0 : _a.url),
+                status: reply.statusCode || ((_b = reply.raw) === null || _b === void 0 ? void 0 : _b.statusCode),
+                ip_address: request.ip || ((_d = (_c = request.raw) === null || _c === void 0 ? void 0 : _c.connection) === null || _d === void 0 ? void 0 : _d.remoteAddress),
+                timestamp: new Date().toISOString(),
+                latency: Math.round(latency),
+            };
+            this.sendLog(logEntry);
+        };
+    }
+    async sendLog(logEntry) {
+        try {
+            const response = await fetch(`${this.baseUrl}/logs/create`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-dyno-api-key': this.apiKey,
+                },
+                body: JSON.stringify(logEntry),
+            });
+            if (!response.ok) {
+                const errBody = await response.text();
+                console.error(`dynosdk: log rejected (${response.status}): ${errBody}`);
+            }
+        }
+        catch (error) {
+            console.error('dynosdk: failed to send log:', error);
+        }
+    }
+}
+exports.DynoClient = DynoClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAEA,MAAa,UAAU;IAIrB,YAAY,OAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,qDAAqD,CAAC;IAC1F,CAAC;IAED;;OAEG;IACI,aAAa;QAClB,OAAO,CAAC,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAEzB,oCAAoC;YACpC,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;;gBACpB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;gBAEnC,MAAM,QAAQ,GAAQ;oBACpB,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG;oBAChC,MAAM,EAAE,GAAG,CAAC,UAAU;oBACtB,UAAU,EAAE,GAAG,CAAC,EAAE,KAAI,MAAA,GAAG,CAAC,UAAU,0CAAE,aAAa,CAAA;oBACnD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oBACnC,OAAO;iBACR,CAAC;gBAEF,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;YAEH,IAAI,EAAE,CAAC;QACT,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,oBAAoB;QACzB,OAAO,KAAK,EAAE,OAAY,EAAE,KAAU,EAAE,EAAE;;YACxC,uEAAuE;YACvE,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAEpE,MAAM,QAAQ,GAAQ;gBACpB,IAAI,EAAE,OAAO,CAAC,GAAG,KAAI,MAAA,OAAO,CAAC,GAAG,0CAAE,GAAG,CAAA;gBACrC,MAAM,EAAE,KAAK,CAAC,UAAU,KAAI,MAAA,KAAK,CAAC,GAAG,0CAAE,UAAU,CAAA;gBACjD,UAAU,EAAE,OAAO,CAAC,EAAE,KAAI,MAAA,MAAA,OAAO,CAAC,GAAG,0CAAE,UAAU,0CAAE,aAAa,CAAA;gBAChE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;aAC7B,CAAC;YAEF,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,QAAa;QACjC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,cAAc,EAAE;gBAC1D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,gBAAgB,EAAE,IAAI,CAAC,MAAM;iBAC9B;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;aAC/B,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACtC,OAAO,CAAC,KAAK,CAAC,0BAA0B,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF;AA3ED,gCA2EC"}

package/dist/fastify.d.ts

@@ -0,0 +1,7 @@
+import { DynoClientOptions } from './types';
+/**
+ * Fastify plugin for Dyno observability.
+ * Usage: fastify.register(dynoFastifyPlugin, { apiKey: '...' })
+ */
+export declare function dynoFastifyPlugin(fastify: any, options: DynoClientOptions): Promise<void>;
+//# sourceMappingURL=fastify.d.ts.map

package/dist/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../src/fastify.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,iBAG/E"}

package/dist/fastify.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dynoFastifyPlugin = dynoFastifyPlugin;
+const client_1 = require("./client");
+/**
+ * Fastify plugin for Dyno observability.
+ * Usage: fastify.register(dynoFastifyPlugin, { apiKey: '...' })
+ */
+async function dynoFastifyPlugin(fastify, options) {
+    const client = new client_1.DynoClient(options);
+    fastify.addHook('onResponse', client.logFastifyOnResponse());
+}
+//# sourceMappingURL=fastify.js.map

package/dist/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../src/fastify.ts"],"names":[],"mappings":";;AAOA,8CAGC;AAVD,qCAAsC;AAGtC;;;GAGG;AACI,KAAK,UAAU,iBAAiB,CAAC,OAAY,EAAE,OAA0B;IAC9E,MAAM,MAAM,GAAG,IAAI,mBAAU,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,oBAAoB,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './client';
+export * from './fastify';
+//# 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,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./fastify"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export interface Log {
+    id?: string;
+    path: string;
+    status: number;
+    ip_address?: string;
+    timestamp: string;
+    latency: number;
+}
+export interface DynoClientOptions {
+    apiKey: string;
+    /**
+     * Override the default production base URL.
+     */
+    baseUrl?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,GAAG;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kivia/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Kivia API observability platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "kivia",
+    "observability",
+    "logging",
+    "sdk"
+  ],
+  "author": "winnerx0",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^5.4.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,78 @@
+import { KiviaClientOptions, Log } from './types';
+
+export class KiviaClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(options: KiviaClientOptions) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || 'https://nginx-production-a9aa.up.railway.app/api/v1';
+  }
+
+  /**
+   * Express/Connect middleware for automatically logging requests.
+   */
+  public logMiddleware() {
+    return (req: any, res: any, next: any) => {
+      const start = Date.now();
+
+      // Listen for the response to finish
+      res.on('finish', () => {
+        const latency = Date.now() - start;
+
+        const logEntry: Log = {
+          path: req.originalUrl || req.url,
+          status: res.statusCode,
+          ip_address: req.ip || req.connection?.remoteAddress,
+          timestamp: new Date().toISOString(),
+          latency,
+        };
+
+        this.sendLog(logEntry);
+      });
+
+      next();
+    };
+  }
+
+  /**
+   * Fastify hook variant to be used with the 'onResponse' lifecycle hook.
+   * Usage: fastify.addHook('onResponse', kiviaClient.logFastifyOnResponse());
+   */
+  public logFastifyOnResponse() {
+    return async (request: any, reply: any) => {
+      // reply.getResponseTime() is available in Fastify to get latency in ms
+      const latency = reply.getResponseTime ? reply.getResponseTime() : 0;
+
+      const logEntry: Log = {
+        path: request.url || request.raw?.url,
+        status: reply.statusCode || reply.raw?.statusCode,
+        ip_address: request.ip || request.raw?.connection?.remoteAddress,
+        timestamp: new Date().toISOString(),
+        latency: Math.round(latency),
+      };
+
+      this.sendLog(logEntry);
+    };
+  }
+
+  private async sendLog(logEntry: Log): Promise<void> {
+    try {
+      const response = await fetch(`${this.baseUrl}/logs/create`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-kivia-api-key': this.apiKey,
+        },
+        body: JSON.stringify(logEntry),
+      });
+
+      if (!response.ok) {
+        const errBody = await response.text();
+        console.error(`kiviasdk: log rejected (${response.status}): ${errBody}`);
+      }
+    } catch (error) {
+      console.error('kiviasdk: failed to send log:', error);
+    }
+  }
+}

package/src/fastify.ts

@@ -0,0 +1,11 @@
+import { KiviaClient } from './client';
+import { KiviaClientOptions } from './types';
+
+/**
+ * Fastify plugin for Kivia observability.
+ * Usage: fastify.register(kiviaFastifyPlugin, { apiKey: '...' })
+ */
+export async function kiviaFastifyPlugin(fastify: any, options: KiviaClientOptions) {
+  const client = new KiviaClient(options);
+  fastify.addHook('onResponse', client.logFastifyOnResponse());
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './client';
+export * from './fastify';

package/src/types.ts

@@ -0,0 +1,16 @@
+export interface Log {
+  id?: string;
+  path: string;
+  status: number;
+  ip_address?: string;
+  timestamp: string; // ISO 8601
+  latency: number; // milliseconds
+}
+
+export interface KiviaClientOptions {
+  apiKey: string;
+  /**
+   * Override the default production base URL.
+   */
+  baseUrl?: string;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2018",
+    "module": "commonjs",
+    "lib": ["ES2022", "DOM"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}