@codecks/fetch 0.1.8 → 1.0.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) {

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
@@ -126,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",
@@ -149,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 });
@@ -173,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.8",
+  "version": "1.0.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 };