nexustrade 0.1.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,49 @@
1
+ /**
2
+ * Minimal `.env` support, zero dependencies.
3
+ *
4
+ * The SDK reads process environment variables. That is the correct primary
5
+ * source — but it surprises people, because writing credentials into a `.env`
6
+ * file is the near-universal local convention, and a client that ignores one
7
+ * fails with "requires an API key" while the key is sitting right there on disk.
8
+ *
9
+ * So the client falls back to a `.env` file. Deliberately narrow:
10
+ *
11
+ * - **The real environment always wins.** A `.env` value is used only when the
12
+ * variable is absent from `process.env`. A stale file must never silently
13
+ * override what you exported.
14
+ * - **Nothing is mutated.** `process.env` is left alone, so importing this SDK
15
+ * cannot change how unrelated code in the same process reads its own config.
16
+ * - **Only NexusTrade's own variables are consumed.** The file is parsed in
17
+ * full, but the client asks for `NEXUSTRADE_*` and nothing else.
18
+ *
19
+ * Kept byte-for-byte equivalent to `env.py` in the Python SDK; the parser rules
20
+ * below are the shared contract.
21
+ *
22
+ * Node 20.6+ ships `process.loadEnvFile()`, but it mutates `process.env` and
23
+ * this package supports Node 18 — so the walk and parse live here.
24
+ */
25
+ /** True when the caller opted out through the real environment. */
26
+ export declare function dotenvDisabled(): boolean;
27
+ /**
28
+ * Parse `.env` text.
29
+ *
30
+ * Rules, shared with the Python SDK:
31
+ *
32
+ * - blank lines and lines whose first non-space character is `#` are skipped
33
+ * - an optional leading `export` is ignored
34
+ * - everything before the first `=` is the key; the rest is the value
35
+ * - a value wrapped in matching single or double quotes is unquoted;
36
+ * double-quoted values also resolve `\n`, `\r`, `\t`, `\\`, `\"`
37
+ * - an unquoted value is taken literally to end of line, after trimming.
38
+ * Inline `#` comments are NOT stripped — a token may legitimately contain
39
+ * `#`, and silently truncating a credential is worse than keeping a trailing
40
+ * comment nobody writes.
41
+ * - the FIRST occurrence of a key wins, matching the "never override" stance
42
+ */
43
+ export declare function parseDotenv(text: string): Record<string, string>;
44
+ /** First `.env` at or above `start` (default: the current directory). */
45
+ export declare function findDotenv(start?: string): string | null;
46
+ /** Values from the nearest `.env`. Never throws; unreadable means empty. */
47
+ export declare function loadDotenvValues(start?: string): Record<string, string>;
48
+ /** `process.env` first, then `.env`. Blank is treated as absent. */
49
+ export declare function environmentValue(name: string, dotenv?: Record<string, string>): string | undefined;
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Minimal `.env` support, zero dependencies.
3
+ *
4
+ * The SDK reads process environment variables. That is the correct primary
5
+ * source — but it surprises people, because writing credentials into a `.env`
6
+ * file is the near-universal local convention, and a client that ignores one
7
+ * fails with "requires an API key" while the key is sitting right there on disk.
8
+ *
9
+ * So the client falls back to a `.env` file. Deliberately narrow:
10
+ *
11
+ * - **The real environment always wins.** A `.env` value is used only when the
12
+ * variable is absent from `process.env`. A stale file must never silently
13
+ * override what you exported.
14
+ * - **Nothing is mutated.** `process.env` is left alone, so importing this SDK
15
+ * cannot change how unrelated code in the same process reads its own config.
16
+ * - **Only NexusTrade's own variables are consumed.** The file is parsed in
17
+ * full, but the client asks for `NEXUSTRADE_*` and nothing else.
18
+ *
19
+ * Kept byte-for-byte equivalent to `env.py` in the Python SDK; the parser rules
20
+ * below are the shared contract.
21
+ *
22
+ * Node 20.6+ ships `process.loadEnvFile()`, but it mutates `process.env` and
23
+ * this package supports Node 18 — so the walk and parse live here.
24
+ */
25
+ import { existsSync, readFileSync } from "node:fs";
26
+ import { dirname, join, resolve } from "node:path";
27
+ // A pathological symlink loop or a very deep tree should not turn credential
28
+ // resolution into an unbounded walk.
29
+ const MAX_PARENTS = 32;
30
+ const DISABLE_VARIABLE = "NEXUSTRADE_DISABLE_DOTENV";
31
+ const ESCAPES = {
32
+ n: "\n",
33
+ r: "\r",
34
+ t: "\t",
35
+ "\\": "\\",
36
+ '"': '"',
37
+ };
38
+ /** True when the caller opted out through the real environment. */
39
+ export function dotenvDisabled() {
40
+ const value = (process.env[DISABLE_VARIABLE] ?? "").trim().toLowerCase();
41
+ return value !== "" && value !== "0" && value !== "false" && value !== "no";
42
+ }
43
+ function unescape(value) {
44
+ let out = "";
45
+ for (let index = 0; index < value.length; index += 1) {
46
+ const character = value[index];
47
+ if (character === "\\" && index + 1 < value.length) {
48
+ const replacement = ESCAPES[value[index + 1]];
49
+ if (replacement !== undefined) {
50
+ out += replacement;
51
+ index += 1;
52
+ continue;
53
+ }
54
+ }
55
+ out += character;
56
+ }
57
+ return out;
58
+ }
59
+ /**
60
+ * Parse `.env` text.
61
+ *
62
+ * Rules, shared with the Python SDK:
63
+ *
64
+ * - blank lines and lines whose first non-space character is `#` are skipped
65
+ * - an optional leading `export` is ignored
66
+ * - everything before the first `=` is the key; the rest is the value
67
+ * - a value wrapped in matching single or double quotes is unquoted;
68
+ * double-quoted values also resolve `\n`, `\r`, `\t`, `\\`, `\"`
69
+ * - an unquoted value is taken literally to end of line, after trimming.
70
+ * Inline `#` comments are NOT stripped — a token may legitimately contain
71
+ * `#`, and silently truncating a credential is worse than keeping a trailing
72
+ * comment nobody writes.
73
+ * - the FIRST occurrence of a key wins, matching the "never override" stance
74
+ */
75
+ export function parseDotenv(text) {
76
+ const values = {};
77
+ for (const rawLine of text.split(/\r?\n/)) {
78
+ let line = rawLine.trim();
79
+ if (!line || line.startsWith("#"))
80
+ continue;
81
+ if (line.startsWith("export "))
82
+ line = line.slice("export ".length).trimStart();
83
+ const separator = line.indexOf("=");
84
+ if (separator === -1)
85
+ continue;
86
+ const key = line.slice(0, separator).trim();
87
+ if (!key || Object.prototype.hasOwnProperty.call(values, key))
88
+ continue;
89
+ let value = line.slice(separator + 1).trim();
90
+ if (value.length >= 2 &&
91
+ value[0] === value[value.length - 1] &&
92
+ (value[0] === "'" || value[0] === '"')) {
93
+ const quote = value[0];
94
+ value = value.slice(1, -1);
95
+ if (quote === '"')
96
+ value = unescape(value);
97
+ }
98
+ values[key] = value;
99
+ }
100
+ return values;
101
+ }
102
+ /** First `.env` at or above `start` (default: the current directory). */
103
+ export function findDotenv(start) {
104
+ let current;
105
+ try {
106
+ current = resolve(start ?? process.cwd());
107
+ }
108
+ catch {
109
+ return null;
110
+ }
111
+ for (let depth = 0; depth < MAX_PARENTS; depth += 1) {
112
+ const candidate = join(current, ".env");
113
+ try {
114
+ if (existsSync(candidate))
115
+ return candidate;
116
+ }
117
+ catch {
118
+ return null;
119
+ }
120
+ const parent = dirname(current);
121
+ if (parent === current)
122
+ break;
123
+ current = parent;
124
+ }
125
+ return null;
126
+ }
127
+ /** Values from the nearest `.env`. Never throws; unreadable means empty. */
128
+ export function loadDotenvValues(start) {
129
+ if (dotenvDisabled())
130
+ return {};
131
+ const path = findDotenv(start);
132
+ if (path === null)
133
+ return {};
134
+ try {
135
+ return parseDotenv(readFileSync(path, "utf8"));
136
+ }
137
+ catch {
138
+ // A malformed or unreadable file must not break a client that was going to
139
+ // be handed an explicit key anyway.
140
+ return {};
141
+ }
142
+ }
143
+ /** `process.env` first, then `.env`. Blank is treated as absent. */
144
+ export function environmentValue(name, dotenv) {
145
+ const live = process.env[name];
146
+ if (live && live.trim())
147
+ return live;
148
+ const values = dotenv ?? loadDotenvValues();
149
+ const fallback = values[name];
150
+ return fallback && fallback.trim() ? fallback : undefined;
151
+ }