@gitkraken/api-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-09
+
+### Added
+
+- Initial release of `@gitkraken/api-tools`: a validation-agnostic HTTP/auth `Transport`, the `HttpError` type, and the `ApiRequest`/`ApiClientConfig` port types, extracted from `@gitkraken/milestones-tools` so they can back the broader v1 API library.
+- Content-type-aware empty-body handling: a `204` (or an empty body with no/JSON content-type) resolves with `undefined` data, while an empty body the server typed as non-JSON (e.g. `text/plain`) resolves with `''`.

package/LICENSE

@@ -0,0 +1,19 @@
+Core Tools License
+
+Copyright (c) 2025-2026 Axosoft, LLC dba GitKraken ("GitKraken")
+
+This software and associated documentation files (the "Software") may be compiled as part of GitKraken software products, including the gitkraken/vscode-gitlens open source project (collectively, the "GitKraken Products"), to the extent the Software is a required component of the GitKraken Products; provided, however, that the Software and its functionality may only be used if you (and any entity that you represent) have agreed to, and are in compliance with, the GitKraken End User License Agreement, available at https://gitkraken.com/eula (the "EULA"), or other agreement governing the use of the Software, as agreed by you and GitKraken, and otherwise have a valid subscription for the correct number of user seats for the applicable version of the Software (e.g., GitLens Free+, GitLens Pro, GitLens Teams, and GitLens Enterprise).
+
+The Software is licensed, not sold. This license only gives you some rights to use the Software. GitKraken reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the Software only as expressly permitted in this license. In doing so, you must comply with any technical limitations in the Software that only allow you to use it in certain ways. You may not (i) work around any technical limitations in the Software, (ii) reverse engineer, decompile or disassemble the Software, or otherwise attempt to derive the source code for the Software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included with the Software, (iii) remove, minimize, block or modify any notices of GitKraken or its suppliers in the Software, (iv) use the software in any way that is against the law, (v) host, share, publish, rent or lease the Software; (vi) distribute the Software as a stand-alone or integrated offering or combine it with any of your applications for others to use, (vii) use the Software other than in connection with validly licensed GitKraken Products or (viii) use any portion of the Software to create software with the same or similar functionality.
+
+You agree that GitKraken and/or its licensors (as applicable) retain all right, title and interest in and to the Software and all modifications and/or patches thereto. You are not granted any other rights beyond what is expressly stated herein. Except as set forth above, it is forbidden to copy, merge, publish, distribute, sublicense, modify and/or sell the Software.
+
+If you give feedback about the Software to GitKraken, you give to GitKraken, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires GitKraken to license its software or documentation to third parties because we include your feedback in them. These rights survive this License.
+
+The full text of this Core Tools License shall be included in all copies or substantial portions of the Software.
+
+This License and the EULA, if applicable, are the entire agreement for the Software. You must comply with all domestic and international export laws and regulations that apply to the Software, which include restrictions on destinations, end users and end use. This License is governed and construed by the laws of the State of Arizona, United States without regard to any choice or conflict of law principles or rules.
+
+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 GITKRAKEN, 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.
+
+For all third party components incorporated into the Software, those components are licensed under the original license provided by the owner of the applicable component.

package/README.md

@@ -0,0 +1,9 @@
+# @gitkraken/api-tools
+
+Validation-agnostic HTTP/auth transport for GitKraken client SDKs.
+
+`Transport` wraps a host-injected request function (or a default `globalThis.fetch`
+requester), attaches a fresh bearer token per request, unwraps the identity-service
+`{ data, error }` envelope, and surfaces non-2xx (and 3xx redirects) as a typed
+`HttpError`. Callers narrow the unwrapped data by passing an optional `parse` hook;
+the transport itself owns no schema library.

package/dist/config.d.ts

@@ -0,0 +1,45 @@
+//#region src/config.d.ts
+/** A single HTTP request the library asks the host to perform. */
+interface ApiRequestOptions {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  signal?: AbortSignal;
+}
+/** The structured response an {@link ApiRequest} resolves to. */
+interface ApiResponse {
+  body: unknown;
+  status: number;
+  statusText?: string;
+  headers: Headers;
+}
+/**
+ * The request function the host injects so the library never owns the network.
+ * It takes a request and resolves a `{ body, status, headers }` response, the
+ * same shape GitKraken's other client SDKs use (e.g. `@gitkraken/provider-apis`
+ * via `contextFreeMakeRequest`). When omitted, the library uses a default
+ * implementation over `globalThis.fetch`.
+ */
+type ApiRequest = (options: ApiRequestOptions) => Promise<ApiResponse>;
+/** Optional structured logger. All methods are no-ops when omitted. */
+interface LoggerPort {
+  debug(msg: string, meta?: unknown): void;
+  warn(msg: string, meta?: unknown): void;
+  error(msg: string, meta?: unknown): void;
+}
+/**
+ * Configuration for the HTTP transport.
+ *
+ * `request` is injected so the host owns the network (proxies, on-prem hosts,
+ * custom TLS); when omitted the transport uses a default `fetch`-based
+ * requester. `getToken` is called per request to supply a fresh bearer token.
+ */
+interface ApiClientConfig {
+  baseUrl: string;
+  getToken: () => Promise<string>;
+  request?: ApiRequest;
+  logger?: LoggerPort;
+}
+//#endregion
+export { ApiClientConfig, ApiRequest, ApiRequestOptions, ApiResponse, LoggerPort };

package/dist/config.js

@@ -0,0 +1 @@
+export{};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { ApiClientConfig, ApiRequest, ApiRequestOptions, ApiResponse, LoggerPort } from "./config.js";
+import { ApiResult, HttpError, RequestInput, Transport } from "./transport.js";
+export { type ApiClientConfig, type ApiRequest, type ApiRequestOptions, type ApiResponse, type ApiResult, HttpError, type LoggerPort, type RequestInput, Transport };

package/dist/index.js

@@ -0,0 +1 @@
+import{HttpError as e,Transport as t}from"./transport.js";export{e as HttpError,t as Transport};

package/dist/transport.d.ts

@@ -0,0 +1,50 @@
+import { ApiClientConfig } from "./config.js";
+
+//#region src/transport.d.ts
+/** A non-2xx (or enveloped-error) response surfaced as a typed error carrying the parsed body. */
+declare class HttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+  readonly headers: Headers;
+  constructor(status: number, body: unknown, headers: Headers);
+}
+interface RequestInput<T> {
+  method: string;
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+  /** Validates and narrows the unwrapped envelope data at the boundary. */
+  parse?: (data: unknown) => T;
+}
+/** A successful response: the unwrapped (and optionally parsed) `data` plus the status and response headers. */
+interface ApiResult<T> {
+  /** `undefined` when the response carried no body (e.g. `204 No Content`). */
+  data: T | undefined;
+  status: number;
+  headers: Headers;
+}
+/**
+ * Thin HTTP layer over the injected request function. Builds the URL, attaches
+ * a fresh bearer token and JSON headers, then maps the structured response to an
+ * {@link ApiResult} carrying the status and headers alongside the data:
+ *
+ * - A `204 No Content`, or an empty JSON body, resolves with `undefined` data
+ *   (it never throws on success), so a caller can distinguish it from a falsy
+ *   JSON value via the returned `status`/`headers`. An empty non-JSON body (e.g.
+ *   an empty `text/plain`) resolves with `''` rather than `undefined`.
+ * - A non-2xx response (or a 2xx carrying a non-null envelope `error`) becomes
+ *   an {@link HttpError}.
+ * - A JSON body is parsed and the identity-service `{ data, error }` envelope
+ *   unwrapped to its `data`, which an optional `parse` then validates; a parse
+ *   failure on a JSON body is surfaced as an {@link HttpError}.
+ * - A non-JSON body (per `Content-Type`) is handed back untouched.
+ */
+declare class Transport {
+  private readonly config;
+  private readonly requester;
+  constructor(config: ApiClientConfig);
+  request<T>(input: RequestInput<T>): Promise<ApiResult<T>>;
+}
+//#endregion
+export { ApiResult, HttpError, RequestInput, Transport };

package/dist/transport.js

@@ -0,0 +1 @@
+var e=class extends Error{status;body;headers;constructor(e,t,n){super(`HTTP ${e}`),this.name=`HttpError`,this.status=e,this.body=t,this.headers=n}};const t=async e=>{let t=await globalThis.fetch(e.url,{method:e.method,headers:e.headers,body:e.body===void 0?void 0:JSON.stringify(e.body),signal:e.signal,redirect:`manual`}),n=await t.text();return{body:n.length===0?null:n,status:t.status,statusText:t.statusText,headers:t.headers}};var n=class{config;requester;constructor(e){this.config=e,this.requester=e.request??t}async request(t){let n=await this.config.getToken(),s=await this.requester({method:t.method,url:`${this.config.baseUrl}${t.path}`,headers:{Authorization:`Bearer ${n}`,"Content-Type":`application/json`,...t.headers},body:t.body,signal:t.signal}),{status:c,headers:l}=s,u=c>=200&&c<300,d=l.get(`content-type`),f=i(l,`application/json`);if(c===204||r(s.body)){if(!u)throw new e(c,s.body??null,l);return c!==204&&d!=null&&!f?{data:t.parse?t.parse(``):``,status:c,headers:l}:{data:void 0,status:c,headers:l}}let p=a(s.body,f,c,l);if(!u)throw new e(c,p,l);if(typeof s.body==`string`&&!f)return{data:t.parse?t.parse(p):p,status:c,headers:l};let m=o(p,c,l);return{data:t.parse?t.parse(m):m,status:c,headers:l}}};function r(e){return e==null||typeof e==`string`&&e.length===0}function i(e,t){return(e.get(`content-type`)?.toLowerCase())?.startsWith(t.toLowerCase())??!1}function a(t,n,r,i){if(typeof t!=`string`||!n)return t;try{return JSON.parse(t)}catch{throw new e(r,t,i)}}function o(t,n,r){if(typeof t!=`object`||!t)throw new e(n,t,r);if(`data`in t||`error`in t){let i=t;if(i.error!=null)throw new e(n,t,r);return i.data}return t}export{e as HttpError,n as Transport};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@gitkraken/api-tools",
+  "version": "0.1.0",
+  "description": "Validation-agnostic HTTP/auth transport for GitKraken client SDKs (token-per-request, envelope unwrapping).",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Axosoft, LLC dba GitKraken",
+  "engines": {
+    "node": ">= 22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "build": "tsdown --config-loader=unrun",
+    "build:dev": "tsdown --config tsdown.dev.config.ts --config-loader=unrun",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}