@codecks/fetch 0.1.7 → 1.0.0-rc.0

package/README.md

@@ -11,26 +11,51 @@ npm install @codecks/fetch
 ## Getting started
 
 ```ts
-import {buildFetchersWithSimpleLoader} from "@codecks/fetch";
-
-const {fetchFromRoot, fetchInstance, fetchInstances, fetchFromInstance} =
-  buildFetchersWithSimpleLoader({
-    baseUrl: "https://api.codecks.io/",
-    subdomain: "my-org",
-    accessToken: "your-token",
-  });
+import {buildFetchers} from "@codecks/fetch";
+
+const {fetchFromRoot, fetchInstance, fetchInstances, fetchFromInstance} = buildFetchers({
+  token: "cdxat_…",
+});
 ```
 
+`token` is an organization token (`cdxat_…`) or a personal token (`cdxut_…`). Create one under
+**Organization Settings → Integrations → API Tokens** or **Your Profile → API Tokens**. It is sent
+as `Authorization: Bearer <token>` and already names its organization, so no subdomain is needed.
+
 ### Configuration options
 
-| Option        | Type                     | Description                    |
-| ------------- | ------------------------ | ------------------------------ |
-| `baseUrl`     | `string`                 | API base URL                   |
-| `subdomain`   | `string`                 | Sets the `X-Account` header    |
-| `accessToken` | `string`                 | Sets the `X-Auth-Token` header |
-| `headers`     | `Record<string, string>` | Additional request headers     |
-| `timeout`     | `number`                 | Request timeout in ms          |
-| `fetch`       | `typeof fetch`           | Custom fetch implementation    |
+| Option    | Type                     | Description                                          |
+| --------- | ------------------------ | ---------------------------------------------------- |
+| `token`   | `string`                 | API token, `cdxat_…` or `cdxut_…` (required)         |
+| `baseUrl` | `string`                 | API base URL, defaults to `https://api.codecks.io/`  |
+| `headers` | `Record<string, string>` | Additional request headers                           |
+| `timeout` | `number`                 | Request timeout in ms; the request aborts after that |
+| `fetch`   | `typeof fetch`           | Custom fetch implementation                          |
+
+### Errors
+
+A non-2xx answer throws a `CodecksApiError`:
+
+```ts
+import {CodecksApiError} from "@codecks/fetch";
+
+try {
+  await fetchFromRoot({account: {fields: ["name"]}});
+} catch (e) {
+  if (e instanceof CodecksApiError) {
+    e.status; // 400, 401, 403, 429, …
+    e.code; // "invalid_token", "token_expired", "missing_scope", "unknown_field", …
+    e.path; // "_root.account.cards.titel" for a query error
+    e.body; // the full response body, e.g. `hint` or `requiredScope`
+  }
+}
+```
+
+### Legacy tokens
+
+`buildLegacyFetchers({accessToken, subdomain, baseUrl, …})` sends the old `X-Auth-Token` and
+`X-Account` headers. The API stops accepting `X-Auth-Token` on **2026-12-31**; move to an API token
+before then.
 
 ## Fetching data
 
@@ -324,9 +349,9 @@ Point your LLM's project instructions (e.g. `CLAUDE.md`) at `schema/overview.md`
 For advanced use cases (batching, caching, custom transports), you can provide your own `DataLoader`:
 
 ```ts
-import {buildFetchers} from "@codecks/fetch";
+import {buildFetchersFromLoader} from "@codecks/fetch";
 
-const {fetchFromRoot} = buildFetchers({
+const {fetchFromRoot} = buildFetchersFromLoader({
   fetchModel: async (model, ids, query) => {
     // your custom loading logic
     return recordOfResults;

package/dist/_exploration/api-requester.d.ts

@@ -1,6 +1,6 @@
 import "../query-type-BqQ9oX_U.js";
 import "../index-k-KPWV9R.js";
-import { FetchOptions } from "../loader-utils-BqZKAn_v.js";
+import { FetchOptions } from "../loader-utils-hvdC-xsQ.js";
 import { BaseRequester, MissingDataRequest } from "../loader-types-fd5tV0FD.js";
 
 //#region src/_exploration/api-requester.d.ts

package/dist/_exploration/api-requester.js

@@ -1,4 +1,4 @@
-import { configuredFetch, ensureMapValue } from "../collection-utils-CYJaA1a9.js";
+import { bearerTransport, configuredFetch, ensureMapValue } from "../collection-utils-T3bx0BS1.js";
 import { serializeModel } from "../query-helpers-iX1fiqLv.js";
 
 //#region src/_exploration/utils/concurrency-limiter.ts
@@ -66,7 +66,7 @@ var ApiRequester = class {
 	fetchOptions;
 	limiter;
 	constructor(fetchOptions, maxConcurrent = 3) {
-		this.fetchOptions = fetchOptions;
+		this.fetchOptions = bearerTransport(fetchOptions);
 		this.limiter = new ConcurrencyLimiter(maxConcurrent);
 	}
 	async request(requests) {
@@ -108,11 +108,23 @@ var ApiRequester = class {
 			key: "",
 			partialInstance: instances
 		});
-		else for (const [id, data] of Object.entries(instances)) results.push({
-			model: modelName,
-			key: id,
-			partialInstance: data
-		});
+		else for (const [id, data] of Object.entries(instances)) {
+			if (data == null) {
+				const requested = dataByModel.get(modelName)?.get(id);
+				if (!requested) continue;
+				results.push({
+					model: modelName,
+					key: id,
+					partialInstance: Object.fromEntries([...requested.fields, ...requested.relations.keys()].map((key) => [key, null]))
+				});
+				continue;
+			}
+			results.push({
+				model: modelName,
+				key: id,
+				partialInstance: data
+			});
+		}
 		return results;
 	}
 };

package/dist/_exploration/store.js

@@ -118,6 +118,9 @@ var Store = class {
 						data[`~${fieldName}`] = cachedValue.value.map((v) => `${v}`);
 						data[fieldName] = relationResults.map((result) => result.data);
 						if (relationResults.some((result) => !result.allPresent)) allPresent = false;
+					} else if (cachedValue.value == null) {
+						data[`~${fieldName}`] = null;
+						data[fieldName] = null;
 					} else {
 						const relationResult = this.checkQueryRecursive(relatedModelDesc, relatedModel, `${cachedValue.value}`, relQuery, missingRequests, acceptDirty);
 						data[`~${fieldName}`] = cachedValue.value != null ? `${cachedValue.value}` : null;

package/dist/collection-utils-T3bx0BS1.js

@@ -0,0 +1,78 @@
+//#region src/loaders/loader-utils.ts
+const DEFAULT_BASE_URL = "https://api.codecks.io/";
+const bearerTransport = (opts) => {
+	const { token,...rest } = opts;
+	if (!/^cdx[au]t_/.test(token)) throw new Error("Expected an API token starting with `cdxat_` or `cdxut_`. Legacy tokens need `buildLegacyFetchers`.");
+	return {
+		baseUrl: DEFAULT_BASE_URL,
+		...rest,
+		authHeaders: { Authorization: `Bearer ${token}` }
+	};
+};
+const legacyTransport = (opts) => {
+	const { accessToken, subdomain,...rest } = opts;
+	const authHeaders = {};
+	if (accessToken) authHeaders["X-Auth-Token"] = accessToken;
+	if (subdomain) authHeaders["X-Account"] = subdomain;
+	return {
+		...rest,
+		authHeaders
+	};
+};
+/** A non-2xx answer. `code`, `path` and the rest of the body follow the API's error format. */
+var CodecksApiError = class extends Error {
+	status;
+	/** e.g. `invalid_token`, `token_expired`, `missing_scope`, `unknown_field`, `rate_limit` */
+	code;
+	/** where in the query the error sits, e.g. `_root.account.cards.titel` */
+	path;
+	/** the parsed JSON body, or the raw text if it wasn't JSON — holds `hint`, `requiredScope`, … */
+	body;
+	constructor(status, body) {
+		const obj = typeof body === "object" && body !== null ? body : {};
+		const str = (v) => typeof v === "string" ? v : null;
+		const code = str(obj.error);
+		super(`[${status}] ${str(obj.message) ?? code ?? (str(body) || "request failed")}`);
+		this.name = "CodecksApiError";
+		this.status = status;
+		this.code = code;
+		this.path = str(obj.path);
+		this.body = body;
+	}
+};
+const readErrorBody = async (r) => {
+	const text = await r.text();
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+};
+const configuredFetch = async (opts, url, init = {}) => {
+	const fetchImpl = opts.fetch || globalThis.fetch;
+	const headers = new Headers(init.headers);
+	for (const [key, value] of Object.entries(opts.authHeaders)) headers.set(key, value);
+	if (opts.headers) for (const [key, value] of Object.entries(opts.headers)) headers.set(key, value);
+	const fullUrl = opts.baseUrl ? `${opts.baseUrl}${url}` : url;
+	const signal = opts.timeout ? AbortSignal.timeout(opts.timeout) : init.signal;
+	const r = await fetchImpl(fullUrl, {
+		...init,
+		headers,
+		signal
+	});
+	if (r.status < 200 || r.status >= 300) throw new CodecksApiError(r.status, await readErrorBody(r));
+	return await r.json();
+};
+
+//#endregion
+//#region src/collection-utils.ts
+const ensureMapValue = (map, key, fallback) => {
+	const exist = map.get(key);
+	if (exist) return exist;
+	const newValue = fallback();
+	map.set(key, newValue);
+	return newValue;
+};
+
+//#endregion
+export { CodecksApiError, bearerTransport, configuredFetch, ensureMapValue, legacyTransport };

package/dist/index.d.ts

@@ -1,11 +1,8 @@
 import { InferModelQuery, InferRelQuery, Instance, ModelQuery, RelQuery } from "./query-type-BqQ9oX_U.js";
 import { modelMap$1 as modelMap } from "./index-k-KPWV9R.js";
-import { DataLoader, FetchOptions } from "./loader-utils-BqZKAn_v.js";
+import { CodecksApiError$1 as CodecksApiError, DataLoader, FetchOptions, LegacyFetchOptions } from "./loader-utils-hvdC-xsQ.js";
 import { _rootDesc$1 as _rootDesc } from "./_root-BW9uzB79.js";
 
-//#region src/loaders/simple-loader.d.ts
-type SimpleLoaderOptions = FetchOptions;
-//#endregion
 //#region src/index.d.ts
 type ModelMap = typeof modelMap;
 type Fetchers = {
@@ -14,7 +11,9 @@ type Fetchers = {
   fetchInstance: <K extends keyof ModelMap, const Q extends ModelQuery<ModelMap[K], ModelMap>>(model: K, id: string, q: Q) => Promise<InferModelQuery<ModelMap[K], Q, ModelMap>>;
   fetchInstances: <K extends keyof ModelMap, Id extends string, const Q extends ModelQuery<ModelMap[K], ModelMap>>(model: K, id: Id[], q: Q) => Promise<Record<Id, InferModelQuery<ModelMap[K], Q, ModelMap>>>;
 };
-declare const buildFetchersWithSimpleLoader: (opts: SimpleLoaderOptions) => Fetchers;
-declare const buildFetchers: (loader: DataLoader) => Fetchers;
+declare const buildFetchers: (opts: FetchOptions) => Fetchers;
+/** @deprecated `X-Auth-Token` stops working on 2026-12-31. Use `buildFetchers` with an API token. */
+declare const buildLegacyFetchers: (opts: LegacyFetchOptions) => Fetchers;
+declare const buildFetchersFromLoader: (loader: DataLoader) => Fetchers;
 //#endregion
-export { buildFetchers, buildFetchersWithSimpleLoader };
+export { CodecksApiError, type DataLoader, type FetchOptions, type LegacyFetchOptions, buildFetchers, buildFetchersFromLoader, buildLegacyFetchers };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { configuredFetch, ensureMapValue } from "./collection-utils-CYJaA1a9.js";
+import { CodecksApiError, bearerTransport, configuredFetch, ensureMapValue, legacyTransport } from "./collection-utils-T3bx0BS1.js";
 import { _rootDesc, getRelKey, makeModelQuerySerializable, modelMap, serializeInstanceQuery } from "./query-helpers-iX1fiqLv.js";
 
 //#region src/model-pool.ts
@@ -41,6 +41,7 @@ var ModelPool = class {
 		Object.entries(data).forEach(([modelName, payload]) => {
 			if (modelName === _rootDesc.name) this.addModelInstance(modelName, ROOT_ID, payload);
 			else Object.entries(payload).forEach(([id, payload$1]) => {
+				if (payload$1 == null) return;
 				this.addModelInstance(modelName, id, payload$1);
 			});
 		});
@@ -53,10 +54,16 @@ var ModelPool = class {
 
 //#endregion
 //#region src/reconcile-query.ts
+/**
+* The API names an id but answers `null` for it when the token may not read that
+* record. Such an id never enters the pool, and the caller can do nothing about it —
+* unlike an id the response never mentioned at all, which points at a bug worth a warning.
+*/
+const isWithheldByApi = (response, model, key) => response[model]?.[key] === null;
 const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 	const instance = store.get(instanceModel.name, key);
 	if (!instance) {
-		console.warn(`no instance found in pool: [${instanceModel.name}, ${key}]`);
+		if (!isWithheldByApi(response, instanceModel.name, key)) console.warn(`no instance found in pool: [${instanceModel.name}, ${key}]`);
 		return null;
 	}
 	const result = instanceModel.name === "_root" ? {} : {
@@ -80,7 +87,7 @@ const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 					break;
 				case "hasOne":
 					result[`~${relName}`] = instance[relName] != null ? `${instance[relName]}` : null;
-					result[relName] = reconcileInstanceQuery(relEntry, response, relModel, `${instance[relName]}`, store);
+					result[relName] = instance[relName] != null ? reconcileInstanceQuery(relEntry, response, relModel, `${instance[relName]}`, store) : null;
 					break;
 				case "hasMany":
 					const asName = relEntry.as ?? relName;
@@ -94,12 +101,20 @@ const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 						}
 						case "first":
 							result[`~${asName}`] = val != null ? `${val}` : null;
-							result[asName] = reconcileInstanceQuery(relEntry, response, relModel, `${val}`, store);
+							result[asName] = val != null ? reconcileInstanceQuery(relEntry, response, relModel, `${val}`, store) : null;
 							break;
 						default: {
 							const ids = val ?? [];
-							result[`~${asName}`] = ids.map((v) => `${v}`);
-							result[asName] = ids.map((id) => reconcileInstanceQuery(relEntry, response, relModel, `${id}`, store));
+							const members = [];
+							for (const id of ids) {
+								const instance$1 = reconcileInstanceQuery(relEntry, response, relModel, `${id}`, store);
+								if (instance$1 != null) members.push({
+									key: `${id}`,
+									instance: instance$1
+								});
+							}
+							result[`~${asName}`] = members.map((m) => m.key);
+							result[asName] = members.map((m) => m.instance);
 						}
 					}
 					break;
@@ -111,7 +126,7 @@ const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 
 //#endregion
 //#region src/loaders/simple-loader.ts
-const createSimpleLoader = (opts = {}) => {
+const createSimpleLoader = (opts) => {
 	const fetchWithQuery = async (query) => {
 		return configuredFetch(opts, "", {
 			method: "POST",
@@ -134,11 +149,10 @@ const createSimpleLoader = (opts = {}) => {
 
 //#endregion
 //#region src/index.ts
-const buildFetchersWithSimpleLoader = (opts) => {
-	const loader = createSimpleLoader(opts);
-	return buildFetchers(loader);
-};
-const buildFetchers = (loader) => {
+const buildFetchers = (opts) => buildFetchersFromLoader(createSimpleLoader(bearerTransport(opts)));
+/** @deprecated `X-Auth-Token` stops working on 2026-12-31. Use `buildFetchers` with an API token. */
+const buildLegacyFetchers = (opts) => buildFetchersFromLoader(createSimpleLoader(legacyTransport(opts)));
+const buildFetchersFromLoader = (loader) => {
 	return {
 		fetchFromRoot: async (q) => {
 			const res = await loader.fetchModel("_root", [""], { relations: q });
@@ -158,4 +172,4 @@ const buildFetchers = (loader) => {
 };
 
 //#endregion
-export { buildFetchers, buildFetchersWithSimpleLoader };
+export { CodecksApiError, buildFetchers, buildFetchersFromLoader, buildLegacyFetchers };

package/dist/loader-utils-hvdC-xsQ.d.ts

@@ -0,0 +1,42 @@
+import { InferModelQuery, ModelQuery } from "./query-type-BqQ9oX_U.js";
+import { modelMap$1 as modelMap } from "./index-k-KPWV9R.js";
+
+//#region src/loaders/loader-utils.d.ts
+type ModelMap = typeof modelMap;
+type DataLoader = {
+  fetchModel: <K extends keyof ModelMap, Id extends string, const Q extends ModelQuery<ModelMap[K], ModelMap>>(model: K, id: Id[], q: Q) => Promise<Record<Id, InferModelQuery<ModelMap[K], Q, ModelMap>>>;
+};
+type FetchFunction = (url: string, init?: RequestInit) => Promise<Response>;
+type BaseFetchOptions = {
+  fetch?: FetchFunction;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  /** in milliseconds */
+  timeout?: number;
+};
+type FetchOptions = BaseFetchOptions & {
+  /** an organization (`cdxat_…`) or personal (`cdxut_…`) API token */
+  token: string;
+};
+/** @deprecated `X-Auth-Token` stops working on 2026-12-31. Use `FetchOptions` with an API token. */
+type LegacyFetchOptions = BaseFetchOptions & {
+  /** sent as `X-Auth-Token` */
+  accessToken?: string;
+  /** sent as `X-Account` */
+  subdomain?: string;
+};
+/** Fetch options with the auth headers already folded into `headers`. */
+
+/** A non-2xx answer. `code`, `path` and the rest of the body follow the API's error format. */
+declare class CodecksApiError extends Error {
+  readonly status: number;
+  /** e.g. `invalid_token`, `token_expired`, `missing_scope`, `unknown_field`, `rate_limit` */
+  readonly code: string | null;
+  /** where in the query the error sits, e.g. `_root.account.cards.titel` */
+  readonly path: string | null;
+  /** the parsed JSON body, or the raw text if it wasn't JSON — holds `hint`, `requiredScope`, … */
+  readonly body: unknown;
+  constructor(status: number, body: unknown);
+}
+//#endregion
+export { CodecksApiError as CodecksApiError$1, DataLoader, FetchOptions, LegacyFetchOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codecks/fetch",
-  "version": "0.1.7",
+  "version": "1.0.0-rc.0",
   "description": "Quickly create deeply nested queries for the Codecks API with advanced TypeScript support",
   "type": "module",
   "license": "MIT",

package/schema/query-syntax.md

@@ -3,8 +3,8 @@
 ## Basic Query
 
 ```ts
-const {fetchFromRoot, fetchInstance} = buildFetchersWithSimpleLoader({
-  token: "your-api-token",
+const {fetchFromRoot, fetchInstance} = buildFetchers({
+  token: "cdxat_…",
 });
 
 // Fetch from root entry points

package/dist/collection-utils-CYJaA1a9.js

@@ -1,32 +0,0 @@
-//#region src/loaders/loader-utils.ts
-const configuredFetch = async (opts, url, init = {}) => {
-	const fetchImpl = opts.fetch || globalThis.fetch;
-	const headers = new Headers(init.headers);
-	if (opts.accessToken) headers.set("X-Auth-Token", opts.accessToken);
-	if (opts.subdomain) headers.set("X-Account", opts.subdomain);
-	if (opts.headers) Object.entries(opts.headers).forEach(([key, value]) => {
-		headers.set(key, value);
-	});
-	const fullUrl = opts.baseUrl ? `${opts.baseUrl}${url}` : url;
-	return fetchImpl(fullUrl, {
-		...init,
-		headers
-	}).then(async (r) => {
-		const content = await r.json();
-		if (r.status !== 200) throw new Error(`[${r.status}] ${JSON.stringify(content)}`);
-		return content;
-	});
-};
-
-//#endregion
-//#region src/collection-utils.ts
-const ensureMapValue = (map, key, fallback) => {
-	const exist = map.get(key);
-	if (exist) return exist;
-	const newValue = fallback();
-	map.set(key, newValue);
-	return newValue;
-};
-
-//#endregion
-export { configuredFetch, ensureMapValue };

package/dist/loader-utils-BqZKAn_v.d.ts

@@ -1,19 +0,0 @@
-import { InferModelQuery, ModelQuery } from "./query-type-BqQ9oX_U.js";
-import { modelMap$1 as modelMap } from "./index-k-KPWV9R.js";
-
-//#region src/loaders/loader-utils.d.ts
-type ModelMap = typeof modelMap;
-type DataLoader = {
-  fetchModel: <K extends keyof ModelMap, Id extends string, const Q extends ModelQuery<ModelMap[K], ModelMap>>(model: K, id: Id[], q: Q) => Promise<Record<Id, InferModelQuery<ModelMap[K], Q, ModelMap>>>;
-};
-type FetchFunction = (url: string, init?: RequestInit) => Promise<Response>;
-type FetchOptions = {
-  fetch?: FetchFunction;
-  accessToken?: string;
-  subdomain?: string;
-  baseUrl?: string;
-  headers?: Record<string, string>;
-  timeout?: number;
-};
-//#endregion
-export { DataLoader, FetchOptions };