@brickninjaapi/fetch 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 @brickninja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# `@brickninjaapi/fetch`
+
+This package provides a tiny wrapper around native fetch to call the Brick Ninja API that returns typesafe responses.
+
+## Usage
+
+```ts
+import { fetchBrickNinjaApi } from '@brickninjaapi/fetch';
+
+const item = await fetchBrickNinjaApi('/v1/items/1234');
+// -> { id: number, name: string, ... }
+```
+
+## Installation
+
+```sh
+npm i @brickninjaapi/fetch
+```
+
+## Contributing
+
+See [parent readme](../../README.md#contributing).
+
+## License
+
+Licensed under the [MIT License](./LICENSE).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@brickninjaapi/fetch",
+  "version": "0.0.1",
+  "description": "Tiny wrapper around fetch that returns type-safe responses",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brickninja-org/brickninjaapi-ts.git",
+    "directory": "packages/fetch"
+  },
+  "keywords": [
+    "brickninjaapi",
+    "fetch",
+    "brickninja",
+    "api"
+  ],
+  "scripts": {
+    "test": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "5.8.3"
+  },
+  "peerDependencies": {
+    "@brickninjaapi/types": "~0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,126 @@
+import type { AuthenticatedOptions, EndpointType, KnownEndpoint, LocalizedOptions, OptionsByEndpoint } from '@brickninjaapi/types/endpoints';
+import type { SchemaVersion } from '@brickninjaapi/types/schema';
+
+type RequiredKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T];
+
+// if OptionsByEndpoint<Url> has no required keys, make the options parameter optional
+type Args<Url extends string, Schema extends SchemaVersion> = RequiredKeys<OptionsByEndpoint<Url>> extends never
+  ? [endpoint: Url, options?: FetchBrickNinjaApiOptions<Schema> & OptionsByEndpoint<Url> & FetchOptions]
+  : [endpoint: Url, options: FetchBrickNinjaApiOptions<Schema> & OptionsByEndpoint<Url> & FetchOptions]
+
+export async function fetchBrickNinjaApi<
+  Url extends KnownEndpoint | (string & {}),
+  Schema extends SchemaVersion = 'latest',
+>(
+  ...[endpoint, options]: Args<Url, Schema>
+): Promise<EndpointType<Url, Schema>> {
+  const url = new URL('https://brick-ninja-api.vercel.app/');
+
+  if (options.schema) {
+    url.searchParams.set('v', options.schema);
+  }
+  if (hasLanguage(options)) {
+    url.searchParams.set('lang', options.language);
+  }
+  if (hasAccessToken(options)) {
+    url.searchParams.set('access_token', options.accessToken);
+  }
+
+  // build request
+  let request = new Request(url, {
+    // The Brick Ninja API never uses redirects, so we want to error if we encounter one.
+    // We use `manual` instead of `error` here so we can throw our own `BrickNinjaApiError` with the response attached
+    redirect: 'manual',
+
+    // set signal and cache from options
+    signal: options.signal,
+    cache: options.cache
+  });
+
+  // if there is a onRequest handler registered, let it modify the request
+  if(options.onRequest) {
+    request = await options.onRequest(request);
+
+    if(!(request instanceof Request)) {
+      throw new Error(`onRequest has to return a Request`);
+    }
+  }
+
+  // call the API
+  const response = await fetch(request);
+
+  // call the onResponse handler if it exists
+  await options.onResponse?.(response);
+
+  // check if the response is json (`application/json; charset=utf-8`)
+  const isJson = response.headers.get('content-type').startsWith('application/json');
+
+  // censor access token in the url to not leak it in error messages
+  const erroredUrl = hasAccessToken(options)
+    ? url.toString().replace(options.accessToken, '***')
+    : url.toString();
+
+  // check if the response is an error
+  if (!response.ok) {
+    // if the response is JSON, it might have more details in the `text` prop
+    if (isJson) {
+      const error: unknown = await response.json();
+
+      if (typeof error === 'object' && 'text' in error && typeof error.text === 'string') {
+        throw new BrickNinjaApiError(`The Brick Ninja API call to '${erroredUrl}' returned ${response.status} ${response.statusText}: ${error.text}.`, response);
+      }
+    }
+
+    // otherwise just throw error with the status code
+    throw new BrickNinjaApiError(`The Brick Ninja API call to '${erroredUrl}' returned ${response.status} ${response.statusText}.`, response);
+  }
+
+  // if the response is not JSON, throw an error
+  if (!isJson) {
+    throw new BrickNinjaApiError(`The Brick Ninja API call to '${erroredUrl}'did not respond with a JSON response.`, response);
+  }
+
+  // parse the response as JSON
+  const json = await response.json();
+
+  // TODO: catch more errors
+
+  return json;
+}
+
+export type FetchBrickNinjaApiOptions<Schema extends SchemaVersion> = {
+  /** The schema to use when making the API request */
+  schema?: Schema;
+
+  /** onRequest handler allows to modify the request made to the Brick Ninja API. */
+  onRequest?: (request: Request) => Request | Promise<Request>;
+
+  /**
+   * onResponse handler. Called for all responses, successful or not.
+   * Make sure to clone the response in case of consuming the body.
+   */
+  onResponse?: (response: Response) => void | Promise<void>;
+}
+
+export type FetchOptions = {
+  /** @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal */
+  signal?: AbortSignal,
+
+  /** @see https://developer.mozilla.org/en-US/docs/Web/API/Request/cache */
+  cache?: RequestCache,
+}
+
+export class BrickNinjaApiError extends Error {
+  constructor(message: string, public response: Response) {
+    super(message);
+    this.name = 'BrickNinjaApiError';
+  }
+}
+
+function hasLanguage(options: OptionsByEndpoint<any>): options is LocalizedOptions {
+  return 'language' in options;
+}
+
+function hasAccessToken(options: OptionsByEndpoint<any>): options is AuthenticatedOptions {
+  return 'accessToken' in options;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "ES2015"
+  },
+  "include": ["./src"],
+  "exclude": ["node_modules"]
+}