@whereq/cloud 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.
Files changed (9) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +48 -0
  3. package/dist/index.cjs +128 -0
  4. package/dist/index.cjs.map +1 -0
  5. package/dist/index.d.cts +77 -0
  6. package/dist/index.d.ts +77 -0
  7. package/dist/index.js +121 -0
  8. package/dist/index.js.map +1 -0
  9. package/package.json +61 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WhereQ
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,48 @@
1
+ # whereq.cloud — JavaScript / TypeScript SDK
2
+
3
+ Official JS/TS client for the [WhereQ data cloud](https://whereq.cloud) — the versioned,
4
+ metered `/v1` API at **`api.whereq.cloud`**: cost-of-living prices, a cross-region
5
+ cost-of-living comparison, trending hot-lists, autos, equities & market data, and more.
6
+
7
+ Zero runtime dependencies, ESM + CJS, fully typed. Works in Node 18+ and the browser.
8
+ Public endpoints work with no key; metered endpoints take an API key.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm i @whereq/cloud # or: pnpm add @whereq/cloud · yarn add @whereq/cloud
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```ts
19
+ import { Whereq } from "@whereq/cloud";
20
+
21
+ const wq = new Whereq(); // public access
22
+ // const wq = new Whereq({ apiKey: "wq_live_…" }); // metered tier
23
+
24
+ // Cost of living — compare US states, CA provinces, or metros (by rent-series id)
25
+ await wq.costOfLiving("us:California,ca:Ontario,m:3958");
26
+
27
+ // Prices — fuel | food | energy | housing | rent
28
+ await wq.prices({ domain: "rent", region: "us", bedrooms: 2, limit: 10 });
29
+ await wq.price(3958); // one series + full history
30
+ const csv = await wq.pricesCsv({ domain: "fuel", region: "us" });
31
+
32
+ // Discovery
33
+ await wq.catalog(); await wq.categories(); await wq.regions(); await wq.domains();
34
+
35
+ // Finance
36
+ await wq.hotstocks(5);
37
+ await wq.screener({ sector: "Technology" });
38
+
39
+ // Escape hatch — call any /v1 endpoint directly
40
+ await wq.get("/v1/trending", { limit: 10 });
41
+ ```
42
+
43
+ Errors throw `WhereqError` (with `.status`, `.message`, `.url`). A typed response is
44
+ available via `wq.get<MyType>(…)`.
45
+
46
+ ## License
47
+
48
+ MIT © WhereQ
package/dist/index.cjs ADDED
@@ -0,0 +1,128 @@
1
+ 'use strict';
2
+
3
+ Object.defineProperty(exports, '__esModule', { value: true });
4
+
5
+ // src/index.ts
6
+ var VERSION = "0.1.0";
7
+ var DEFAULT_BASE_URL = "https://api.whereq.cloud";
8
+ var WhereqError = class extends Error {
9
+ constructor(status, message, url) {
10
+ super(`whereq.cloud API error ${status} for ${url}: ${message}`);
11
+ this.status = status;
12
+ this.url = url;
13
+ this.name = "WhereqError";
14
+ }
15
+ status;
16
+ url;
17
+ };
18
+ var Whereq = class {
19
+ baseUrl;
20
+ headers;
21
+ _fetch;
22
+ constructor(opts = {}) {
23
+ this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
24
+ this.headers = { Accept: "application/json" };
25
+ if (opts.apiKey) this.headers["X-API-Key"] = opts.apiKey;
26
+ const f = opts.fetch ?? globalThis.fetch;
27
+ if (!f) throw new Error("No global fetch available \u2014 pass `fetch` in options (Node <18).");
28
+ this._fetch = f;
29
+ }
30
+ url(path, params) {
31
+ const qs = new URLSearchParams();
32
+ for (const [k, v] of Object.entries(params)) {
33
+ if (v !== void 0 && v !== null) qs.set(k, String(v));
34
+ }
35
+ const s = qs.toString();
36
+ return `${this.baseUrl}${path}${s ? `?${s}` : ""}`;
37
+ }
38
+ /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */
39
+ async get(path, params = {}) {
40
+ const url = this.url(path, params);
41
+ const res = await this._fetch(url, { headers: this.headers });
42
+ if (!res.ok) {
43
+ let msg = res.statusText;
44
+ try {
45
+ const j = await res.json();
46
+ msg = j?.detail || JSON.stringify(j) || msg;
47
+ } catch {
48
+ }
49
+ throw new WhereqError(res.status, msg, url);
50
+ }
51
+ return await res.json();
52
+ }
53
+ /** GET a non-JSON endpoint (e.g. CSV export) as text. */
54
+ async getText(path, params = {}) {
55
+ const url = this.url(path, params);
56
+ const res = await this._fetch(url, { headers: this.headers });
57
+ if (!res.ok) throw new WhereqError(res.status, res.statusText, url);
58
+ return res.text();
59
+ }
60
+ // -- prices / cost of living ------------------------------------------------
61
+ prices(p = {}) {
62
+ return this.get("/v1/prices", p);
63
+ }
64
+ price(seriesId) {
65
+ return this.get(`/v1/prices/${seriesId}`);
66
+ }
67
+ pricesCsv(p = {}) {
68
+ return this.getText("/v1/prices/export", p);
69
+ }
70
+ /** Compare cost of living across US states / CA provinces / metros.
71
+ * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */
72
+ costOfLiving(places) {
73
+ return this.get("/v1/cost-of-living", { places });
74
+ }
75
+ // -- discovery / facets -----------------------------------------------------
76
+ catalog() {
77
+ return this.get("/v1/catalog");
78
+ }
79
+ categories() {
80
+ return this.get("/v1/categories");
81
+ }
82
+ regions() {
83
+ return this.get("/v1/regions");
84
+ }
85
+ domains() {
86
+ return this.get("/v1/domains");
87
+ }
88
+ trending(p = {}) {
89
+ return this.get("/v1/trending", p);
90
+ }
91
+ // -- finance ----------------------------------------------------------------
92
+ hotstocks(limit = 20) {
93
+ return this.get("/v1/hotstocks", { limit });
94
+ }
95
+ quotes(p = {}) {
96
+ return this.get("/v1/quotes", p);
97
+ }
98
+ news(p = {}) {
99
+ return this.get("/v1/news", p);
100
+ }
101
+ screener(p = {}) {
102
+ return this.get("/v1/screener", p);
103
+ }
104
+ search(q, p = {}) {
105
+ return this.get("/v1/search", { q, ...p });
106
+ }
107
+ // -- autos ------------------------------------------------------------------
108
+ autosRecalls(p = {}) {
109
+ return this.get("/v1/autos/recalls", p);
110
+ }
111
+ autosListings(p = {}) {
112
+ return this.get("/v1/autos/listings", p);
113
+ }
114
+ autosFuelEconomy(p = {}) {
115
+ return this.get("/v1/autos/fuel-economy", p);
116
+ }
117
+ autosModels(p = {}) {
118
+ return this.get("/v1/autos/models", p);
119
+ }
120
+ };
121
+ var index_default = Whereq;
122
+
123
+ exports.VERSION = VERSION;
124
+ exports.Whereq = Whereq;
125
+ exports.WhereqError = WhereqError;
126
+ exports.default = index_default;
127
+ //# sourceMappingURL=index.cjs.map
128
+ //# sourceMappingURL=index.cjs.map
package/dist/index.cjs.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * whereq.cloud — official JavaScript/TypeScript SDK for the WhereQ data cloud.\n *\n * A thin, typed wrapper over the versioned `/v1` HTTP API at `api.whereq.cloud`.\n * Public endpoints work with no key; metered endpoints take an API key.\n *\n * ```ts\n * import { Whereq } from \"@whereq/cloud\";\n *\n * const wq = new Whereq(); // public access\n * // const wq = new Whereq({ apiKey: \"wq_live_…\" }); // metered tier\n *\n * await wq.costOfLiving(\"us:California,ca:Ontario\");\n * await wq.prices({ domain: \"rent\", region: \"us\", bedrooms: 2 });\n * await wq.get(\"/v1/trending\", { limit: 10 }); // escape hatch\n * ```\n */\nexport const VERSION = \"0.1.0\";\nconst DEFAULT_BASE_URL = \"https://api.whereq.cloud\";\n\nexport class WhereqError extends Error {\n constructor(\n public readonly status: number,\n message: string,\n public readonly url: string,\n ) {\n super(`whereq.cloud API error ${status} for ${url}: ${message}`);\n this.name = \"WhereqError\";\n }\n}\n\nexport interface ClientOptions {\n /** `wq_live_…` key for metered endpoints (sent as `X-API-Key`). */\n apiKey?: string;\n /** Override the API base (default `https://api.whereq.cloud`). */\n baseUrl?: string;\n /** Custom fetch (e.g. for Node <18 or testing). Defaults to global `fetch`. */\n fetch?: typeof fetch;\n}\n\ntype Params = Record<string, unknown>;\n\nexport class Whereq {\n private readonly baseUrl: string;\n private readonly headers: Record<string, string>;\n private readonly _fetch: typeof fetch;\n\n constructor(opts: ClientOptions = {}) {\n this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n this.headers = { Accept: \"application/json\" };\n if (opts.apiKey) this.headers[\"X-API-Key\"] = opts.apiKey;\n const f = opts.fetch ?? globalThis.fetch;\n if (!f) throw new Error(\"No global fetch available — pass `fetch` in options (Node <18).\");\n this._fetch = f;\n }\n\n private url(path: string, params: Params): string {\n const qs = new URLSearchParams();\n for (const [k, v] of Object.entries(params)) {\n if (v !== undefined && v !== null) qs.set(k, String(v));\n }\n const s = qs.toString();\n return `${this.baseUrl}${path}${s ? `?${s}` : \"\"}`;\n }\n\n /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */\n async get<T = unknown>(path: string, params: Params = {}): Promise<T> {\n const url = this.url(path, params);\n const res = await this._fetch(url, { headers: this.headers });\n if (!res.ok) {\n let msg = res.statusText;\n try {\n const j = (await res.json()) as { detail?: string };\n msg = j?.detail || JSON.stringify(j) || msg;\n } catch {\n /* non-JSON error body */\n }\n throw new WhereqError(res.status, msg, url);\n }\n return (await res.json()) as T;\n }\n\n /** GET a non-JSON endpoint (e.g. CSV export) as text. */\n async getText(path: string, params: Params = {}): Promise<string> {\n const url = this.url(path, params);\n const res = await this._fetch(url, { headers: this.headers });\n if (!res.ok) throw new WhereqError(res.status, res.statusText, url);\n return res.text();\n }\n\n // -- prices / cost of living ------------------------------------------------\n prices(p: { domain?: string; region?: string; bedrooms?: number; q?: string; limit?: number; offset?: number } = {}) {\n return this.get(\"/v1/prices\", p);\n }\n price(seriesId: number) {\n return this.get(`/v1/prices/${seriesId}`);\n }\n pricesCsv(p: { domain?: string; region?: string; bedrooms?: number; q?: string } = {}) {\n return this.getText(\"/v1/prices/export\", p);\n }\n /** Compare cost of living across US states / CA provinces / metros.\n * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */\n costOfLiving(places: string) {\n return this.get(\"/v1/cost-of-living\", { places });\n }\n\n // -- discovery / facets -----------------------------------------------------\n catalog() { return this.get(\"/v1/catalog\"); }\n categories() { return this.get(\"/v1/categories\"); }\n regions() { return this.get(\"/v1/regions\"); }\n domains() { return this.get(\"/v1/domains\"); }\n trending(p: Params = {}) { return this.get(\"/v1/trending\", p); }\n\n // -- finance ----------------------------------------------------------------\n hotstocks(limit = 20) { return this.get(\"/v1/hotstocks\", { limit }); }\n quotes(p: Params = {}) { return this.get(\"/v1/quotes\", p); }\n news(p: Params = {}) { return this.get(\"/v1/news\", p); }\n screener(p: Params = {}) { return this.get(\"/v1/screener\", p); }\n search(q: string, p: Params = {}) { return this.get(\"/v1/search\", { q, ...p }); }\n\n // -- autos ------------------------------------------------------------------\n autosRecalls(p: Params = {}) { return this.get(\"/v1/autos/recalls\", p); }\n autosListings(p: Params = {}) { return this.get(\"/v1/autos/listings\", p); }\n autosFuelEconomy(p: Params = {}) { return this.get(\"/v1/autos/fuel-economy\", p); }\n autosModels(p: Params = {}) { return this.get(\"/v1/autos/models\", p); }\n}\n\nexport default Whereq;\n"]}
package/dist/index.d.cts ADDED
@@ -0,0 +1,77 @@
1
+ /**
2
+ * whereq.cloud — official JavaScript/TypeScript SDK for the WhereQ data cloud.
3
+ *
4
+ * A thin, typed wrapper over the versioned `/v1` HTTP API at `api.whereq.cloud`.
5
+ * Public endpoints work with no key; metered endpoints take an API key.
6
+ *
7
+ * ```ts
8
+ * import { Whereq } from "@whereq/cloud";
9
+ *
10
+ * const wq = new Whereq(); // public access
11
+ * // const wq = new Whereq({ apiKey: "wq_live_…" }); // metered tier
12
+ *
13
+ * await wq.costOfLiving("us:California,ca:Ontario");
14
+ * await wq.prices({ domain: "rent", region: "us", bedrooms: 2 });
15
+ * await wq.get("/v1/trending", { limit: 10 }); // escape hatch
16
+ * ```
17
+ */
18
+ declare const VERSION = "0.1.0";
19
+ declare class WhereqError extends Error {
20
+ readonly status: number;
21
+ readonly url: string;
22
+ constructor(status: number, message: string, url: string);
23
+ }
24
+ interface ClientOptions {
25
+ /** `wq_live_…` key for metered endpoints (sent as `X-API-Key`). */
26
+ apiKey?: string;
27
+ /** Override the API base (default `https://api.whereq.cloud`). */
28
+ baseUrl?: string;
29
+ /** Custom fetch (e.g. for Node <18 or testing). Defaults to global `fetch`. */
30
+ fetch?: typeof fetch;
31
+ }
32
+ type Params = Record<string, unknown>;
33
+ declare class Whereq {
34
+ private readonly baseUrl;
35
+ private readonly headers;
36
+ private readonly _fetch;
37
+ constructor(opts?: ClientOptions);
38
+ private url;
39
+ /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */
40
+ get<T = unknown>(path: string, params?: Params): Promise<T>;
41
+ /** GET a non-JSON endpoint (e.g. CSV export) as text. */
42
+ getText(path: string, params?: Params): Promise<string>;
43
+ prices(p?: {
44
+ domain?: string;
45
+ region?: string;
46
+ bedrooms?: number;
47
+ q?: string;
48
+ limit?: number;
49
+ offset?: number;
50
+ }): Promise<unknown>;
51
+ price(seriesId: number): Promise<unknown>;
52
+ pricesCsv(p?: {
53
+ domain?: string;
54
+ region?: string;
55
+ bedrooms?: number;
56
+ q?: string;
57
+ }): Promise<string>;
58
+ /** Compare cost of living across US states / CA provinces / metros.
59
+ * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */
60
+ costOfLiving(places: string): Promise<unknown>;
61
+ catalog(): Promise<unknown>;
62
+ categories(): Promise<unknown>;
63
+ regions(): Promise<unknown>;
64
+ domains(): Promise<unknown>;
65
+ trending(p?: Params): Promise<unknown>;
66
+ hotstocks(limit?: number): Promise<unknown>;
67
+ quotes(p?: Params): Promise<unknown>;
68
+ news(p?: Params): Promise<unknown>;
69
+ screener(p?: Params): Promise<unknown>;
70
+ search(q: string, p?: Params): Promise<unknown>;
71
+ autosRecalls(p?: Params): Promise<unknown>;
72
+ autosListings(p?: Params): Promise<unknown>;
73
+ autosFuelEconomy(p?: Params): Promise<unknown>;
74
+ autosModels(p?: Params): Promise<unknown>;
75
+ }
76
+
77
+ export { type ClientOptions, VERSION, Whereq, WhereqError, Whereq as default };
package/dist/index.d.ts ADDED
@@ -0,0 +1,77 @@
1
+ /**
2
+ * whereq.cloud — official JavaScript/TypeScript SDK for the WhereQ data cloud.
3
+ *
4
+ * A thin, typed wrapper over the versioned `/v1` HTTP API at `api.whereq.cloud`.
5
+ * Public endpoints work with no key; metered endpoints take an API key.
6
+ *
7
+ * ```ts
8
+ * import { Whereq } from "@whereq/cloud";
9
+ *
10
+ * const wq = new Whereq(); // public access
11
+ * // const wq = new Whereq({ apiKey: "wq_live_…" }); // metered tier
12
+ *
13
+ * await wq.costOfLiving("us:California,ca:Ontario");
14
+ * await wq.prices({ domain: "rent", region: "us", bedrooms: 2 });
15
+ * await wq.get("/v1/trending", { limit: 10 }); // escape hatch
16
+ * ```
17
+ */
18
+ declare const VERSION = "0.1.0";
19
+ declare class WhereqError extends Error {
20
+ readonly status: number;
21
+ readonly url: string;
22
+ constructor(status: number, message: string, url: string);
23
+ }
24
+ interface ClientOptions {
25
+ /** `wq_live_…` key for metered endpoints (sent as `X-API-Key`). */
26
+ apiKey?: string;
27
+ /** Override the API base (default `https://api.whereq.cloud`). */
28
+ baseUrl?: string;
29
+ /** Custom fetch (e.g. for Node <18 or testing). Defaults to global `fetch`. */
30
+ fetch?: typeof fetch;
31
+ }
32
+ type Params = Record<string, unknown>;
33
+ declare class Whereq {
34
+ private readonly baseUrl;
35
+ private readonly headers;
36
+ private readonly _fetch;
37
+ constructor(opts?: ClientOptions);
38
+ private url;
39
+ /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */
40
+ get<T = unknown>(path: string, params?: Params): Promise<T>;
41
+ /** GET a non-JSON endpoint (e.g. CSV export) as text. */
42
+ getText(path: string, params?: Params): Promise<string>;
43
+ prices(p?: {
44
+ domain?: string;
45
+ region?: string;
46
+ bedrooms?: number;
47
+ q?: string;
48
+ limit?: number;
49
+ offset?: number;
50
+ }): Promise<unknown>;
51
+ price(seriesId: number): Promise<unknown>;
52
+ pricesCsv(p?: {
53
+ domain?: string;
54
+ region?: string;
55
+ bedrooms?: number;
56
+ q?: string;
57
+ }): Promise<string>;
58
+ /** Compare cost of living across US states / CA provinces / metros.
59
+ * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */
60
+ costOfLiving(places: string): Promise<unknown>;
61
+ catalog(): Promise<unknown>;
62
+ categories(): Promise<unknown>;
63
+ regions(): Promise<unknown>;
64
+ domains(): Promise<unknown>;
65
+ trending(p?: Params): Promise<unknown>;
66
+ hotstocks(limit?: number): Promise<unknown>;
67
+ quotes(p?: Params): Promise<unknown>;
68
+ news(p?: Params): Promise<unknown>;
69
+ screener(p?: Params): Promise<unknown>;
70
+ search(q: string, p?: Params): Promise<unknown>;
71
+ autosRecalls(p?: Params): Promise<unknown>;
72
+ autosListings(p?: Params): Promise<unknown>;
73
+ autosFuelEconomy(p?: Params): Promise<unknown>;
74
+ autosModels(p?: Params): Promise<unknown>;
75
+ }
76
+
77
+ export { type ClientOptions, VERSION, Whereq, WhereqError, Whereq as default };
package/dist/index.js ADDED
@@ -0,0 +1,121 @@
1
+ // src/index.ts
2
+ var VERSION = "0.1.0";
3
+ var DEFAULT_BASE_URL = "https://api.whereq.cloud";
4
+ var WhereqError = class extends Error {
5
+ constructor(status, message, url) {
6
+ super(`whereq.cloud API error ${status} for ${url}: ${message}`);
7
+ this.status = status;
8
+ this.url = url;
9
+ this.name = "WhereqError";
10
+ }
11
+ status;
12
+ url;
13
+ };
14
+ var Whereq = class {
15
+ baseUrl;
16
+ headers;
17
+ _fetch;
18
+ constructor(opts = {}) {
19
+ this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
20
+ this.headers = { Accept: "application/json" };
21
+ if (opts.apiKey) this.headers["X-API-Key"] = opts.apiKey;
22
+ const f = opts.fetch ?? globalThis.fetch;
23
+ if (!f) throw new Error("No global fetch available \u2014 pass `fetch` in options (Node <18).");
24
+ this._fetch = f;
25
+ }
26
+ url(path, params) {
27
+ const qs = new URLSearchParams();
28
+ for (const [k, v] of Object.entries(params)) {
29
+ if (v !== void 0 && v !== null) qs.set(k, String(v));
30
+ }
31
+ const s = qs.toString();
32
+ return `${this.baseUrl}${path}${s ? `?${s}` : ""}`;
33
+ }
34
+ /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */
35
+ async get(path, params = {}) {
36
+ const url = this.url(path, params);
37
+ const res = await this._fetch(url, { headers: this.headers });
38
+ if (!res.ok) {
39
+ let msg = res.statusText;
40
+ try {
41
+ const j = await res.json();
42
+ msg = j?.detail || JSON.stringify(j) || msg;
43
+ } catch {
44
+ }
45
+ throw new WhereqError(res.status, msg, url);
46
+ }
47
+ return await res.json();
48
+ }
49
+ /** GET a non-JSON endpoint (e.g. CSV export) as text. */
50
+ async getText(path, params = {}) {
51
+ const url = this.url(path, params);
52
+ const res = await this._fetch(url, { headers: this.headers });
53
+ if (!res.ok) throw new WhereqError(res.status, res.statusText, url);
54
+ return res.text();
55
+ }
56
+ // -- prices / cost of living ------------------------------------------------
57
+ prices(p = {}) {
58
+ return this.get("/v1/prices", p);
59
+ }
60
+ price(seriesId) {
61
+ return this.get(`/v1/prices/${seriesId}`);
62
+ }
63
+ pricesCsv(p = {}) {
64
+ return this.getText("/v1/prices/export", p);
65
+ }
66
+ /** Compare cost of living across US states / CA provinces / metros.
67
+ * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */
68
+ costOfLiving(places) {
69
+ return this.get("/v1/cost-of-living", { places });
70
+ }
71
+ // -- discovery / facets -----------------------------------------------------
72
+ catalog() {
73
+ return this.get("/v1/catalog");
74
+ }
75
+ categories() {
76
+ return this.get("/v1/categories");
77
+ }
78
+ regions() {
79
+ return this.get("/v1/regions");
80
+ }
81
+ domains() {
82
+ return this.get("/v1/domains");
83
+ }
84
+ trending(p = {}) {
85
+ return this.get("/v1/trending", p);
86
+ }
87
+ // -- finance ----------------------------------------------------------------
88
+ hotstocks(limit = 20) {
89
+ return this.get("/v1/hotstocks", { limit });
90
+ }
91
+ quotes(p = {}) {
92
+ return this.get("/v1/quotes", p);
93
+ }
94
+ news(p = {}) {
95
+ return this.get("/v1/news", p);
96
+ }
97
+ screener(p = {}) {
98
+ return this.get("/v1/screener", p);
99
+ }
100
+ search(q, p = {}) {
101
+ return this.get("/v1/search", { q, ...p });
102
+ }
103
+ // -- autos ------------------------------------------------------------------
104
+ autosRecalls(p = {}) {
105
+ return this.get("/v1/autos/recalls", p);
106
+ }
107
+ autosListings(p = {}) {
108
+ return this.get("/v1/autos/listings", p);
109
+ }
110
+ autosFuelEconomy(p = {}) {
111
+ return this.get("/v1/autos/fuel-economy", p);
112
+ }
113
+ autosModels(p = {}) {
114
+ return this.get("/v1/autos/models", p);
115
+ }
116
+ };
117
+ var index_default = Whereq;
118
+
119
+ export { VERSION, Whereq, WhereqError, index_default as default };
120
+ //# sourceMappingURL=index.js.map
121
+ //# sourceMappingURL=index.js.map
package/dist/index.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * whereq.cloud — official JavaScript/TypeScript SDK for the WhereQ data cloud.\n *\n * A thin, typed wrapper over the versioned `/v1` HTTP API at `api.whereq.cloud`.\n * Public endpoints work with no key; metered endpoints take an API key.\n *\n * ```ts\n * import { Whereq } from \"@whereq/cloud\";\n *\n * const wq = new Whereq(); // public access\n * // const wq = new Whereq({ apiKey: \"wq_live_…\" }); // metered tier\n *\n * await wq.costOfLiving(\"us:California,ca:Ontario\");\n * await wq.prices({ domain: \"rent\", region: \"us\", bedrooms: 2 });\n * await wq.get(\"/v1/trending\", { limit: 10 }); // escape hatch\n * ```\n */\nexport const VERSION = \"0.1.0\";\nconst DEFAULT_BASE_URL = \"https://api.whereq.cloud\";\n\nexport class WhereqError extends Error {\n constructor(\n public readonly status: number,\n message: string,\n public readonly url: string,\n ) {\n super(`whereq.cloud API error ${status} for ${url}: ${message}`);\n this.name = \"WhereqError\";\n }\n}\n\nexport interface ClientOptions {\n /** `wq_live_…` key for metered endpoints (sent as `X-API-Key`). */\n apiKey?: string;\n /** Override the API base (default `https://api.whereq.cloud`). */\n baseUrl?: string;\n /** Custom fetch (e.g. for Node <18 or testing). Defaults to global `fetch`. */\n fetch?: typeof fetch;\n}\n\ntype Params = Record<string, unknown>;\n\nexport class Whereq {\n private readonly baseUrl: string;\n private readonly headers: Record<string, string>;\n private readonly _fetch: typeof fetch;\n\n constructor(opts: ClientOptions = {}) {\n this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n this.headers = { Accept: \"application/json\" };\n if (opts.apiKey) this.headers[\"X-API-Key\"] = opts.apiKey;\n const f = opts.fetch ?? globalThis.fetch;\n if (!f) throw new Error(\"No global fetch available — pass `fetch` in options (Node <18).\");\n this._fetch = f;\n }\n\n private url(path: string, params: Params): string {\n const qs = new URLSearchParams();\n for (const [k, v] of Object.entries(params)) {\n if (v !== undefined && v !== null) qs.set(k, String(v));\n }\n const s = qs.toString();\n return `${this.baseUrl}${path}${s ? `?${s}` : \"\"}`;\n }\n\n /** GET any endpoint; `undefined`/`null` params are dropped. Returns parsed JSON. */\n async get<T = unknown>(path: string, params: Params = {}): Promise<T> {\n const url = this.url(path, params);\n const res = await this._fetch(url, { headers: this.headers });\n if (!res.ok) {\n let msg = res.statusText;\n try {\n const j = (await res.json()) as { detail?: string };\n msg = j?.detail || JSON.stringify(j) || msg;\n } catch {\n /* non-JSON error body */\n }\n throw new WhereqError(res.status, msg, url);\n }\n return (await res.json()) as T;\n }\n\n /** GET a non-JSON endpoint (e.g. CSV export) as text. */\n async getText(path: string, params: Params = {}): Promise<string> {\n const url = this.url(path, params);\n const res = await this._fetch(url, { headers: this.headers });\n if (!res.ok) throw new WhereqError(res.status, res.statusText, url);\n return res.text();\n }\n\n // -- prices / cost of living ------------------------------------------------\n prices(p: { domain?: string; region?: string; bedrooms?: number; q?: string; limit?: number; offset?: number } = {}) {\n return this.get(\"/v1/prices\", p);\n }\n price(seriesId: number) {\n return this.get(`/v1/prices/${seriesId}`);\n }\n pricesCsv(p: { domain?: string; region?: string; bedrooms?: number; q?: string } = {}) {\n return this.getText(\"/v1/prices/export\", p);\n }\n /** Compare cost of living across US states / CA provinces / metros.\n * `places`: comma-separated `region:name` or `m:<rent-series-id>`. */\n costOfLiving(places: string) {\n return this.get(\"/v1/cost-of-living\", { places });\n }\n\n // -- discovery / facets -----------------------------------------------------\n catalog() { return this.get(\"/v1/catalog\"); }\n categories() { return this.get(\"/v1/categories\"); }\n regions() { return this.get(\"/v1/regions\"); }\n domains() { return this.get(\"/v1/domains\"); }\n trending(p: Params = {}) { return this.get(\"/v1/trending\", p); }\n\n // -- finance ----------------------------------------------------------------\n hotstocks(limit = 20) { return this.get(\"/v1/hotstocks\", { limit }); }\n quotes(p: Params = {}) { return this.get(\"/v1/quotes\", p); }\n news(p: Params = {}) { return this.get(\"/v1/news\", p); }\n screener(p: Params = {}) { return this.get(\"/v1/screener\", p); }\n search(q: string, p: Params = {}) { return this.get(\"/v1/search\", { q, ...p }); }\n\n // -- autos ------------------------------------------------------------------\n autosRecalls(p: Params = {}) { return this.get(\"/v1/autos/recalls\", p); }\n autosListings(p: Params = {}) { return this.get(\"/v1/autos/listings\", p); }\n autosFuelEconomy(p: Params = {}) { return this.get(\"/v1/autos/fuel-economy\", p); }\n autosModels(p: Params = {}) { return this.get(\"/v1/autos/models\", p); }\n}\n\nexport default Whereq;\n"]}
package/package.json ADDED
@@ -0,0 +1,61 @@
1
+ {
2
+ "name": "@whereq/cloud",
3
+ "version": "0.1.0",
4
+ "description": "Official JavaScript/TypeScript SDK for the WhereQ data cloud (api.whereq.cloud) — cost-of-living prices, comparisons, trending, finance & more.",
5
+ "license": "MIT",
6
+ "author": "WhereQ <whereq@gmail.com>",
7
+ "type": "module",
8
+ "main": "./dist/index.cjs",
9
+ "module": "./dist/index.js",
10
+ "types": "./dist/index.d.ts",
11
+ "exports": {
12
+ ".": {
13
+ "types": "./dist/index.d.ts",
14
+ "import": "./dist/index.js",
15
+ "require": "./dist/index.cjs"
16
+ },
17
+ "./package.json": "./package.json"
18
+ },
19
+ "files": [
20
+ "dist",
21
+ "README.md",
22
+ "LICENSE"
23
+ ],
24
+ "sideEffects": false,
25
+ "engines": {
26
+ "node": ">=18"
27
+ },
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "git+https://github.com/whereq/whereq-cloud-js.git"
31
+ },
32
+ "homepage": "https://whereq.cloud",
33
+ "bugs": "https://github.com/whereq/whereq-cloud-js/issues",
34
+ "keywords": [
35
+ "whereq",
36
+ "data",
37
+ "api",
38
+ "cost-of-living",
39
+ "prices",
40
+ "trending",
41
+ "finance",
42
+ "sdk"
43
+ ],
44
+ "devDependencies": {
45
+ "@changesets/cli": "^2.27.9",
46
+ "tsup": "^8.3.0",
47
+ "typescript": "^5.7.2",
48
+ "vitest": "^2.1.0"
49
+ },
50
+ "publishConfig": {
51
+ "access": "public",
52
+ "provenance": true
53
+ },
54
+ "scripts": {
55
+ "build": "tsup",
56
+ "typecheck": "tsc --noEmit",
57
+ "test": "vitest run",
58
+ "verify": "pnpm run typecheck && pnpm run test && pnpm run build",
59
+ "release": "pnpm run build && changeset publish"
60
+ }
61
+ }