zeno.id 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,88 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ //#region src/server/node.ts
3
+ const MAX_BODY = 131073;
4
+ const readBody = async (request, parsedBody) => {
5
+ if (request.method !== "POST") return;
6
+ if (request.readableEnded) {
7
+ if (typeof parsedBody === "string") return parsedBody;
8
+ if (parsedBody instanceof Uint8Array) return new TextDecoder().decode(parsedBody);
9
+ return parsedBody === void 0 ? "" : JSON.stringify(parsedBody);
10
+ }
11
+ const chunks = [];
12
+ let size = 0;
13
+ for await (const chunk of request) {
14
+ const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
15
+ if (size < MAX_BODY) chunks.push(bytes);
16
+ size += bytes.byteLength;
17
+ }
18
+ const body = new Uint8Array(Math.min(size, MAX_BODY));
19
+ let offset = 0;
20
+ for (const chunk of chunks) {
21
+ const part = chunk.subarray(0, body.length - offset);
22
+ body.set(part, offset);
23
+ offset += part.byteLength;
24
+ }
25
+ return new TextDecoder().decode(body);
26
+ };
27
+ const toWebRequest = async (request, parsedBody) => {
28
+ const headers = new Headers();
29
+ for (let index = 0; index + 1 < request.rawHeaders.length; index += 2) {
30
+ const name = request.rawHeaders[index];
31
+ if (!name.startsWith(":")) headers.append(name, request.rawHeaders[index + 1]);
32
+ }
33
+ const protocol = request.socket.encrypted ? "https" : "http";
34
+ const path = request.originalUrl ?? request.url ?? "/";
35
+ const host = request.headers.host ?? request.headers[":authority"] ?? "localhost";
36
+ const body = await readBody(request, parsedBody);
37
+ return new Request(new URL(path, `${protocol}://${String(host)}`), {
38
+ method: request.method,
39
+ headers,
40
+ ...body === void 0 ? {} : { body }
41
+ });
42
+ };
43
+ const writeResponse = async (response, nodeResponse) => {
44
+ nodeResponse.statusCode = response.status;
45
+ response.headers.forEach((value, name) => {
46
+ if (name !== "set-cookie") nodeResponse.setHeader(name, value);
47
+ });
48
+ const cookies = response.headers.getSetCookie();
49
+ if (cookies.length > 0) nodeResponse.setHeader("set-cookie", cookies);
50
+ nodeResponse.end(response.body ? new Uint8Array(await response.arrayBuffer()) : void 0);
51
+ };
52
+ /**
53
+ * Mounts the proxy route on Node's `(req, res)`: Express, Fastify or `http.createServer`. `app.all('/zeno',
54
+ * nodeHandler(zeno))`, with `zeno` from `createProxy`. It passes the IP address the request came from: Express's and
55
+ * Fastify's `req.ip` (behind a proxy of your own, set their trust proxy so it's the visitor's), else the socket's
56
+ * address. A body parser in front (`express.json()`) is fine.
57
+ */
58
+ const nodeHandler = (handler) => {
59
+ const handlerWithRawHeaders = handler;
60
+ return async (request, response) => {
61
+ const req = "raw" in request ? request.raw : request;
62
+ const frameworkIp = request.ip;
63
+ const ip = typeof frameworkIp === "string" ? frameworkIp : req.socket.remoteAddress;
64
+ const parsedBody = "raw" in request ? request.body : request.body;
65
+ let res;
66
+ if ("hijack" in response) {
67
+ response.hijack();
68
+ res = response.raw;
69
+ } else res = response;
70
+ try {
71
+ const webRequest = await toWebRequest(req, parsedBody);
72
+ const answer = await handlerWithRawHeaders(webRequest, ip, { rawHeaders: req.rawHeaders });
73
+ await writeResponse(answer, res);
74
+ } catch (error) {
75
+ console.error(`The proxy route failed: ${error instanceof Error ? error.message : String(error)}`);
76
+ if (!res.headersSent) {
77
+ res.statusCode = 500;
78
+ res.setHeader("content-type", "application/json; charset=utf-8");
79
+ res.end(JSON.stringify({
80
+ error: "server_error",
81
+ message: "The proxy route failed; its server log says why"
82
+ }));
83
+ }
84
+ }
85
+ };
86
+ };
87
+ //#endregion
88
+ exports.nodeHandler = nodeHandler;
@@ -0,0 +1,21 @@
1
+ import { t as ProxyHandler } from "./proxy-CUZ-Jwgy.cjs";
2
+ import { IncomingMessage, ServerResponse } from "http";
3
+ //#region src/server/node.d.ts
4
+ type FastifyRequest = {
5
+ raw: IncomingMessage;
6
+ body?: unknown;
7
+ ip?: unknown;
8
+ };
9
+ type FastifyReply = {
10
+ raw: ServerResponse;
11
+ hijack: () => unknown;
12
+ };
13
+ /**
14
+ * Mounts the proxy route on Node's `(req, res)`: Express, Fastify or `http.createServer`. `app.all('/zeno',
15
+ * nodeHandler(zeno))`, with `zeno` from `createProxy`. It passes the IP address the request came from: Express's and
16
+ * Fastify's `req.ip` (behind a proxy of your own, set their trust proxy so it's the visitor's), else the socket's
17
+ * address. A body parser in front (`express.json()`) is fine.
18
+ */
19
+ declare const nodeHandler: (handler: ProxyHandler) => (request: IncomingMessage | FastifyRequest, response: ServerResponse | FastifyReply) => Promise<void>;
20
+ //#endregion
21
+ export { nodeHandler };
@@ -0,0 +1,21 @@
1
+ import { t as ProxyHandler } from "./proxy-CUZ-Jwgy.js";
2
+ import { IncomingMessage, ServerResponse } from "http";
3
+ //#region src/server/node.d.ts
4
+ type FastifyRequest = {
5
+ raw: IncomingMessage;
6
+ body?: unknown;
7
+ ip?: unknown;
8
+ };
9
+ type FastifyReply = {
10
+ raw: ServerResponse;
11
+ hijack: () => unknown;
12
+ };
13
+ /**
14
+ * Mounts the proxy route on Node's `(req, res)`: Express, Fastify or `http.createServer`. `app.all('/zeno',
15
+ * nodeHandler(zeno))`, with `zeno` from `createProxy`. It passes the IP address the request came from: Express's and
16
+ * Fastify's `req.ip` (behind a proxy of your own, set their trust proxy so it's the visitor's), else the socket's
17
+ * address. A body parser in front (`express.json()`) is fine.
18
+ */
19
+ declare const nodeHandler: (handler: ProxyHandler) => (request: IncomingMessage | FastifyRequest, response: ServerResponse | FastifyReply) => Promise<void>;
20
+ //#endregion
21
+ export { nodeHandler };
@@ -0,0 +1,87 @@
1
+ //#region src/server/node.ts
2
+ const MAX_BODY = 131073;
3
+ const readBody = async (request, parsedBody) => {
4
+ if (request.method !== "POST") return;
5
+ if (request.readableEnded) {
6
+ if (typeof parsedBody === "string") return parsedBody;
7
+ if (parsedBody instanceof Uint8Array) return new TextDecoder().decode(parsedBody);
8
+ return parsedBody === void 0 ? "" : JSON.stringify(parsedBody);
9
+ }
10
+ const chunks = [];
11
+ let size = 0;
12
+ for await (const chunk of request) {
13
+ const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
14
+ if (size < MAX_BODY) chunks.push(bytes);
15
+ size += bytes.byteLength;
16
+ }
17
+ const body = new Uint8Array(Math.min(size, MAX_BODY));
18
+ let offset = 0;
19
+ for (const chunk of chunks) {
20
+ const part = chunk.subarray(0, body.length - offset);
21
+ body.set(part, offset);
22
+ offset += part.byteLength;
23
+ }
24
+ return new TextDecoder().decode(body);
25
+ };
26
+ const toWebRequest = async (request, parsedBody) => {
27
+ const headers = new Headers();
28
+ for (let index = 0; index + 1 < request.rawHeaders.length; index += 2) {
29
+ const name = request.rawHeaders[index];
30
+ if (!name.startsWith(":")) headers.append(name, request.rawHeaders[index + 1]);
31
+ }
32
+ const protocol = request.socket.encrypted ? "https" : "http";
33
+ const path = request.originalUrl ?? request.url ?? "/";
34
+ const host = request.headers.host ?? request.headers[":authority"] ?? "localhost";
35
+ const body = await readBody(request, parsedBody);
36
+ return new Request(new URL(path, `${protocol}://${String(host)}`), {
37
+ method: request.method,
38
+ headers,
39
+ ...body === void 0 ? {} : { body }
40
+ });
41
+ };
42
+ const writeResponse = async (response, nodeResponse) => {
43
+ nodeResponse.statusCode = response.status;
44
+ response.headers.forEach((value, name) => {
45
+ if (name !== "set-cookie") nodeResponse.setHeader(name, value);
46
+ });
47
+ const cookies = response.headers.getSetCookie();
48
+ if (cookies.length > 0) nodeResponse.setHeader("set-cookie", cookies);
49
+ nodeResponse.end(response.body ? new Uint8Array(await response.arrayBuffer()) : void 0);
50
+ };
51
+ /**
52
+ * Mounts the proxy route on Node's `(req, res)`: Express, Fastify or `http.createServer`. `app.all('/zeno',
53
+ * nodeHandler(zeno))`, with `zeno` from `createProxy`. It passes the IP address the request came from: Express's and
54
+ * Fastify's `req.ip` (behind a proxy of your own, set their trust proxy so it's the visitor's), else the socket's
55
+ * address. A body parser in front (`express.json()`) is fine.
56
+ */
57
+ const nodeHandler = (handler) => {
58
+ const handlerWithRawHeaders = handler;
59
+ return async (request, response) => {
60
+ const req = "raw" in request ? request.raw : request;
61
+ const frameworkIp = request.ip;
62
+ const ip = typeof frameworkIp === "string" ? frameworkIp : req.socket.remoteAddress;
63
+ const parsedBody = "raw" in request ? request.body : request.body;
64
+ let res;
65
+ if ("hijack" in response) {
66
+ response.hijack();
67
+ res = response.raw;
68
+ } else res = response;
69
+ try {
70
+ const webRequest = await toWebRequest(req, parsedBody);
71
+ const answer = await handlerWithRawHeaders(webRequest, ip, { rawHeaders: req.rawHeaders });
72
+ await writeResponse(answer, res);
73
+ } catch (error) {
74
+ console.error(`The proxy route failed: ${error instanceof Error ? error.message : String(error)}`);
75
+ if (!res.headersSent) {
76
+ res.statusCode = 500;
77
+ res.setHeader("content-type", "application/json; charset=utf-8");
78
+ res.end(JSON.stringify({
79
+ error: "server_error",
80
+ message: "The proxy route failed; its server log says why"
81
+ }));
82
+ }
83
+ }
84
+ };
85
+ };
86
+ //#endregion
87
+ export { nodeHandler };
@@ -0,0 +1,36 @@
1
+ //#region src/server/util.d.ts
2
+ /** The project's API key, `sk_...`, from your server's environment: `process.env.ZENO_API_KEY`. */
3
+ type ApiKey = string | undefined;
4
+ /** Options both createClient and createProxy take. */
5
+ type ApiOptions = {
6
+ /** The Zeno API's http(s) origin, for staging or a local Zeno. Zeno's own API by default. */
7
+ apiUrl?: string | undefined;
8
+ };
9
+ //#endregion
10
+ //#region src/server/proxy.d.ts
11
+ type ProxyOptions = ApiOptions & {
12
+ /**
13
+ * The visitor id cookie's path: the path the browser calls the route on, by default the request's own. Set it when
14
+ * something in front of the handler rewrites the path (the site's `/zeno` handled at `/api/proxy`), else the
15
+ * browser keeps the cookie for a path it never calls and every visit is a new one.
16
+ */
17
+ cookiePath?: string | undefined;
18
+ };
19
+ /**
20
+ * The route's handler, `zeno(request, ip)`: a web `Request` in, a `Response` out. `ip` is the IP address the request
21
+ * came from, your framework's client IP; behind a proxy of your own, turn on your framework's trust-proxy setting so
22
+ * it's the visitor's. An identification without it answers `500`. Answer `GET` and `POST` on one path with it.
23
+ */
24
+ type ProxyHandler = (request: Request, ip: string | null | undefined) => Promise<Response>;
25
+ /**
26
+ * The proxy route: a route on your own site between the browser SDK and the Zeno API. It serves the script's code,
27
+ * forwards its identifications with your API key and the visitor's ip, and keeps the visitor id in a first-party
28
+ * HttpOnly cookie. Answer `GET` and `POST` on one path of your choice (the one the browser's `start()` takes, `/zeno`
29
+ * by default) with what it returns, `zeno(request, ip)` with the IP address the request came from (`nodeHandler(zeno)`
30
+ * from `zeno.id/server/node` on Node's `(req, res)`). The `apiKey` (from your server's environment, undefined accepted)
31
+ * is checked on each request, so a module that makes it at load builds without the environment (as Next.js does when it
32
+ * collects page data); a request without it answers `500` and logs it.
33
+ */
34
+ declare const createProxy: (apiKey: ApiKey, options?: ProxyOptions) => ProxyHandler;
35
+ //#endregion
36
+ export { ApiOptions as a, ApiKey as i, ProxyOptions as n, createProxy as r, ProxyHandler as t };
@@ -0,0 +1,36 @@
1
+ //#region src/server/util.d.ts
2
+ /** The project's API key, `sk_...`, from your server's environment: `process.env.ZENO_API_KEY`. */
3
+ type ApiKey = string | undefined;
4
+ /** Options both createClient and createProxy take. */
5
+ type ApiOptions = {
6
+ /** The Zeno API's http(s) origin, for staging or a local Zeno. Zeno's own API by default. */
7
+ apiUrl?: string | undefined;
8
+ };
9
+ //#endregion
10
+ //#region src/server/proxy.d.ts
11
+ type ProxyOptions = ApiOptions & {
12
+ /**
13
+ * The visitor id cookie's path: the path the browser calls the route on, by default the request's own. Set it when
14
+ * something in front of the handler rewrites the path (the site's `/zeno` handled at `/api/proxy`), else the
15
+ * browser keeps the cookie for a path it never calls and every visit is a new one.
16
+ */
17
+ cookiePath?: string | undefined;
18
+ };
19
+ /**
20
+ * The route's handler, `zeno(request, ip)`: a web `Request` in, a `Response` out. `ip` is the IP address the request
21
+ * came from, your framework's client IP; behind a proxy of your own, turn on your framework's trust-proxy setting so
22
+ * it's the visitor's. An identification without it answers `500`. Answer `GET` and `POST` on one path with it.
23
+ */
24
+ type ProxyHandler = (request: Request, ip: string | null | undefined) => Promise<Response>;
25
+ /**
26
+ * The proxy route: a route on your own site between the browser SDK and the Zeno API. It serves the script's code,
27
+ * forwards its identifications with your API key and the visitor's ip, and keeps the visitor id in a first-party
28
+ * HttpOnly cookie. Answer `GET` and `POST` on one path of your choice (the one the browser's `start()` takes, `/zeno`
29
+ * by default) with what it returns, `zeno(request, ip)` with the IP address the request came from (`nodeHandler(zeno)`
30
+ * from `zeno.id/server/node` on Node's `(req, res)`). The `apiKey` (from your server's environment, undefined accepted)
31
+ * is checked on each request, so a module that makes it at load builds without the environment (as Next.js does when it
32
+ * collects page data); a request without it answers `500` and logs it.
33
+ */
34
+ declare const createProxy: (apiKey: ApiKey, options?: ProxyOptions) => ProxyHandler;
35
+ //#endregion
36
+ export { ApiOptions as a, ApiKey as i, ProxyOptions as n, createProxy as r, ProxyHandler as t };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "zeno.id",
3
- "version": "0.1.0",
4
- "description": "Zeno's browser SDK for device identification: a small loader that fetches the current script from your own route at runtime",
3
+ "version": "0.3.0",
4
+ "description": "Zeno's SDK for device identification: the browser SDK, and the proxy route and API client for your server",
5
5
  "license": "MIT",
6
6
  "files": [
7
7
  "dist"
@@ -11,6 +11,16 @@
11
11
  "main": "./dist/index.cjs",
12
12
  "module": "./dist/index.js",
13
13
  "types": "./dist/index.d.ts",
14
+ "typesVersions": {
15
+ "*": {
16
+ "server": [
17
+ "./dist/server/index.d.ts"
18
+ ],
19
+ "server/node": [
20
+ "./dist/server/node.d.ts"
21
+ ]
22
+ }
23
+ },
14
24
  "exports": {
15
25
  ".": {
16
26
  "import": {
@@ -21,14 +31,35 @@
21
31
  "types": "./dist/index.d.cts",
22
32
  "default": "./dist/index.cjs"
23
33
  }
24
- }
34
+ },
35
+ "./server": {
36
+ "import": {
37
+ "types": "./dist/server/index.d.ts",
38
+ "default": "./dist/server/index.js"
39
+ },
40
+ "require": {
41
+ "types": "./dist/server/index.d.cts",
42
+ "default": "./dist/server/index.cjs"
43
+ }
44
+ },
45
+ "./server/node": {
46
+ "import": {
47
+ "types": "./dist/server/node.d.ts",
48
+ "default": "./dist/server/node.js"
49
+ },
50
+ "require": {
51
+ "types": "./dist/server/node.d.cts",
52
+ "default": "./dist/server/node.cjs"
53
+ }
54
+ },
55
+ "./package.json": "./package.json"
25
56
  },
26
57
  "publishConfig": {
27
58
  "access": "public"
28
59
  },
29
60
  "scripts": {
30
- "test": "bun test ./test/loader.ts",
31
- "build": "tsdown --no-fixed-extension src/index.ts --format cjs,esm --dts --clean --platform browser",
61
+ "test": "bun test ./test/loader.ts ./test/proxy.ts ./test/server.ts ./test/build.ts",
62
+ "build": "bun scripts/build.ts",
32
63
  "prepublishOnly": "if bun run test; then bun run build; else exit; fi",
33
64
  "prepack": "bun ../../scripts/package-exports.ts strip",
34
65
  "postpack": "bun ../../scripts/package-exports.ts restore"