@air/api-core 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -33,6 +33,9 @@ __export(index_exports, {
   RateLimitError: () => RateLimitError,
   TimeoutError: () => TimeoutError,
   VERSION: () => VERSION,
+  buildAuthorizationUrl: () => buildAuthorizationUrl,
+  exchangeAuthorizationCode: () => exchangeAuthorizationCode,
+  generatePKCEChallenge: () => generatePKCEChallenge,
   getRetryDelay: () => getRetryDelay,
   isRetryableError: () => isRetryableError,
   retryWithBackoff: () => retryWithBackoff
@@ -224,6 +227,7 @@ var VERSION = "0.1.0";
 // src/base-client.ts
 var AirBase = class {
   apiKey;
+  accessToken;
   workspaceId;
   baseURL;
   maxRetries;
@@ -231,19 +235,41 @@ var AirBase = class {
   _fetch;
   _defaultHeaders;
   constructor(options = {}) {
-    const apiKey = options.apiKey ?? process.env.AIR_API_KEY;
-    if (!apiKey) {
+    let apiKey;
+    let accessToken;
+    if (options.apiKey !== void 0 && options.accessToken !== void 0) {
       throw new Error(
-        "API key is required. Pass it as `apiKey` option or set the AIR_API_KEY environment variable."
+        "Provide either `apiKey` or `accessToken`, not both. API key auth and OAuth bearer auth are mutually exclusive."
+      );
+    }
+    if (options.apiKey !== void 0) {
+      apiKey = options.apiKey;
+    } else if (options.accessToken !== void 0) {
+      accessToken = options.accessToken;
+    } else {
+      const envApiKey = process.env.AIR_API_KEY;
+      const envAccessToken = process.env.AIR_ACCESS_TOKEN;
+      if (envApiKey && envAccessToken) {
+        throw new Error(
+          "Both AIR_API_KEY and AIR_ACCESS_TOKEN are set. Set only one, or pass `apiKey`/`accessToken` explicitly to choose."
+        );
+      }
+      apiKey = envApiKey;
+      accessToken = envAccessToken;
+    }
+    if (!apiKey && !accessToken) {
+      throw new Error(
+        "Authentication is required. Pass `apiKey` (or set AIR_API_KEY) for API key auth, or `accessToken` (or set AIR_ACCESS_TOKEN) for OAuth bearer auth."
       );
     }
     const workspaceId = options.workspaceId ?? process.env.AIR_WORKSPACE_ID;
-    if (!workspaceId) {
+    if (apiKey && !workspaceId) {
       throw new Error(
-        "Workspace ID is required. Pass it as `workspaceId` option or set the AIR_WORKSPACE_ID environment variable."
+        "Workspace ID is required when using API key authentication. Pass it as `workspaceId` option or set the AIR_WORKSPACE_ID environment variable."
       );
     }
     this.apiKey = apiKey;
+    this.accessToken = accessToken;
     this.workspaceId = workspaceId;
     this.baseURL = (options.baseURL ?? "https://api.air.inc/v1").replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 3;
@@ -282,12 +308,17 @@ var AirBase = class {
   async _executeRequest(options) {
     const url = this._buildURL(options.path, options.query);
     const headers = {
-      "x-api-key": this.apiKey,
-      "x-air-workspace-id": this.workspaceId,
-      "user-agent": `air-api-sdk/${VERSION}`,
-      ...this._defaultHeaders,
-      ...options.headers
+      "user-agent": `air-api-sdk/${VERSION}`
     };
+    if (this.apiKey) {
+      headers["x-api-key"] = this.apiKey;
+    } else if (this.accessToken) {
+      headers["authorization"] = `Bearer ${this.accessToken}`;
+    }
+    if (this.workspaceId) {
+      headers["x-air-workspace-id"] = this.workspaceId;
+    }
+    Object.assign(headers, this._defaultHeaders, options.headers);
     if (options.body !== void 0) {
       headers["content-type"] = "application/json";
     }
@@ -342,6 +373,90 @@ var AirBase = class {
     return url.toString();
   }
 };
+
+// src/oauth.ts
+function buildAuthorizationUrl(options) {
+  const url = new URL(options.authorizeUrl);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("state", options.state);
+  url.searchParams.set("code_challenge", options.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (options.scopes !== void 0) {
+    const scope = Array.isArray(options.scopes) ? options.scopes.join(" ") : options.scopes;
+    if (scope.length > 0) {
+      url.searchParams.set("scope", scope);
+    }
+  }
+  return url.toString();
+}
+async function exchangeAuthorizationCode(options) {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: options.code,
+    code_verifier: options.codeVerifier,
+    redirect_uri: options.redirectUri
+  });
+  const headers = {
+    "content-type": "application/x-www-form-urlencoded"
+  };
+  if (options.clientSecret === void 0) {
+    body.set("client_id", options.clientId);
+  } else {
+    applyClientAuth(headers, body, {
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      method: options.clientAuthMethod ?? "basic"
+    });
+  }
+  return executeTokenRequest(fetchFn, options.tokenUrl, headers, body.toString());
+}
+function applyClientAuth(headers, body, args) {
+  if (args.method === "basic") {
+    headers["authorization"] = `Basic ${base64Encode(`${args.clientId}:${args.clientSecret}`)}`;
+  } else {
+    body.set("client_id", args.clientId);
+    body.set("client_secret", args.clientSecret);
+  }
+}
+async function executeTokenRequest(fetchFn, tokenUrl, headers, body) {
+  let response;
+  try {
+    response = await fetchFn(tokenUrl, { method: "POST", headers, body });
+  } catch (error) {
+    throw new ConnectionError(error instanceof Error ? error.message : "Connection failed");
+  }
+  if (!response.ok) {
+    throw await APIError.fromResponse(response);
+  }
+  const raw = await response.json();
+  return {
+    accessToken: raw.access_token,
+    tokenType: raw.token_type,
+    expiresIn: raw.expires_in,
+    scope: raw.scope,
+    refreshToken: raw.refresh_token
+  };
+}
+function base64Encode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf-8").toString("base64");
+  }
+  return btoa(input);
+}
+
+// src/pkce.ts
+var import_node_crypto = require("crypto");
+function generatePKCEChallenge() {
+  const codeVerifier = base64UrlEncode((0, import_node_crypto.randomBytes)(32));
+  const codeChallenge = base64UrlEncode((0, import_node_crypto.createHash)("sha256").update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge, codeChallengeMethod: "S256" };
+}
+function base64UrlEncode(input) {
+  return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIError,
@@ -357,6 +472,9 @@ var AirBase = class {
   RateLimitError,
   TimeoutError,
   VERSION,
+  buildAuthorizationUrl,
+  exchangeAuthorizationCode,
+  generatePKCEChallenge,
   getRetryDelay,
   isRetryableError,
   retryWithBackoff

package/dist/index.d.cts

@@ -46,6 +46,7 @@ interface RequestOptions {
 
 interface AirBaseOptions {
     apiKey?: string;
+    accessToken?: string;
     workspaceId?: string;
     baseURL?: string;
     maxRetries?: number;
@@ -54,8 +55,9 @@ interface AirBaseOptions {
     defaultHeaders?: Record<string, string>;
 }
 declare class AirBase {
-    readonly apiKey: string;
-    workspaceId: string;
+    readonly apiKey: string | undefined;
+    readonly accessToken: string | undefined;
+    workspaceId: string | undefined;
     readonly baseURL: string;
     readonly maxRetries: number;
     readonly timeout: number;
@@ -108,4 +110,72 @@ declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries: number, m
 
 declare const VERSION = "0.1.0";
 
-export { APIError, AirBase, type AirBaseOptions, AuthenticationError, BadRequestError, ConnectionError, CursorPage, type CursorPageParams, type CursorPageResponse, InternalServerError, NotFoundError, PagePromise, PermissionError, RateLimitError, type RequestOptions, TimeoutError, VERSION, getRetryDelay, isRetryableError, retryWithBackoff };
+/**
+ * How the client authenticates to the OAuth token endpoint.
+ *
+ * - `"basic"` (default for confidential clients) — HTTP Basic auth header
+ *   `Authorization: Basic base64(client_id:client_secret)`. Preferred per
+ *   RFC 6749 §2.3.1.
+ * - `"body"` — credentials sent as `client_id` (+ `client_secret`) form
+ *   fields in the POST body. Useful when an upstream load balancer strips
+ *   `Authorization` headers, or for public clients with no secret.
+ */
+type OAuthClientAuthMethod = "basic" | "body";
+interface OAuthAccessToken {
+    accessToken: string;
+    tokenType: string;
+    expiresIn: number;
+    scope?: string;
+    refreshToken?: string;
+}
+interface BuildAuthorizationUrlOptions {
+    authorizeUrl: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    state: string;
+    scopes?: string | readonly string[];
+}
+/**
+ * Builds the OAuth 2.0 authorization URL for the authorization_code + PKCE
+ * flow. The user is redirected to this URL in a browser; after login + consent
+ * the IdP redirects back to `redirectUri` with a `code` query parameter.
+ */
+declare function buildAuthorizationUrl(options: BuildAuthorizationUrlOptions): string;
+interface ExchangeAuthorizationCodeOptions {
+    tokenUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    /**
+     * Defaults to `"basic"` for confidential clients (those with a
+     * `clientSecret`). Public clients always send `client_id` in the body.
+     */
+    clientAuthMethod?: OAuthClientAuthMethod;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Exchanges an authorization code for an access token using PKCE. Confidential
+ * clients (`clientSecret` provided) authenticate via the method chosen with
+ * `clientAuthMethod`. Public clients always send `client_id` in the body.
+ */
+declare function exchangeAuthorizationCode(options: ExchangeAuthorizationCodeOptions): Promise<OAuthAccessToken>;
+
+interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+/**
+ * Generates a PKCE code verifier and matching S256 challenge per RFC 7636.
+ *
+ * The verifier is 43 base64url characters (32 random bytes encoded). The
+ * challenge is the base64url-encoded SHA-256 hash of the verifier. Use the
+ * challenge in the authorization request and the verifier when exchanging
+ * the resulting code for a token.
+ */
+declare function generatePKCEChallenge(): PKCEChallenge;
+
+export { APIError, AirBase, type AirBaseOptions, AuthenticationError, BadRequestError, type BuildAuthorizationUrlOptions, ConnectionError, CursorPage, type CursorPageParams, type CursorPageResponse, type ExchangeAuthorizationCodeOptions, InternalServerError, NotFoundError, type OAuthAccessToken, type OAuthClientAuthMethod, type PKCEChallenge, PagePromise, PermissionError, RateLimitError, type RequestOptions, TimeoutError, VERSION, buildAuthorizationUrl, exchangeAuthorizationCode, generatePKCEChallenge, getRetryDelay, isRetryableError, retryWithBackoff };

package/dist/index.d.ts

@@ -46,6 +46,7 @@ interface RequestOptions {
 
 interface AirBaseOptions {
     apiKey?: string;
+    accessToken?: string;
     workspaceId?: string;
     baseURL?: string;
     maxRetries?: number;
@@ -54,8 +55,9 @@ interface AirBaseOptions {
     defaultHeaders?: Record<string, string>;
 }
 declare class AirBase {
-    readonly apiKey: string;
-    workspaceId: string;
+    readonly apiKey: string | undefined;
+    readonly accessToken: string | undefined;
+    workspaceId: string | undefined;
     readonly baseURL: string;
     readonly maxRetries: number;
     readonly timeout: number;
@@ -108,4 +110,72 @@ declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries: number, m
 
 declare const VERSION = "0.1.0";
 
-export { APIError, AirBase, type AirBaseOptions, AuthenticationError, BadRequestError, ConnectionError, CursorPage, type CursorPageParams, type CursorPageResponse, InternalServerError, NotFoundError, PagePromise, PermissionError, RateLimitError, type RequestOptions, TimeoutError, VERSION, getRetryDelay, isRetryableError, retryWithBackoff };
+/**
+ * How the client authenticates to the OAuth token endpoint.
+ *
+ * - `"basic"` (default for confidential clients) — HTTP Basic auth header
+ *   `Authorization: Basic base64(client_id:client_secret)`. Preferred per
+ *   RFC 6749 §2.3.1.
+ * - `"body"` — credentials sent as `client_id` (+ `client_secret`) form
+ *   fields in the POST body. Useful when an upstream load balancer strips
+ *   `Authorization` headers, or for public clients with no secret.
+ */
+type OAuthClientAuthMethod = "basic" | "body";
+interface OAuthAccessToken {
+    accessToken: string;
+    tokenType: string;
+    expiresIn: number;
+    scope?: string;
+    refreshToken?: string;
+}
+interface BuildAuthorizationUrlOptions {
+    authorizeUrl: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    state: string;
+    scopes?: string | readonly string[];
+}
+/**
+ * Builds the OAuth 2.0 authorization URL for the authorization_code + PKCE
+ * flow. The user is redirected to this URL in a browser; after login + consent
+ * the IdP redirects back to `redirectUri` with a `code` query parameter.
+ */
+declare function buildAuthorizationUrl(options: BuildAuthorizationUrlOptions): string;
+interface ExchangeAuthorizationCodeOptions {
+    tokenUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+    /**
+     * Defaults to `"basic"` for confidential clients (those with a
+     * `clientSecret`). Public clients always send `client_id` in the body.
+     */
+    clientAuthMethod?: OAuthClientAuthMethod;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Exchanges an authorization code for an access token using PKCE. Confidential
+ * clients (`clientSecret` provided) authenticate via the method chosen with
+ * `clientAuthMethod`. Public clients always send `client_id` in the body.
+ */
+declare function exchangeAuthorizationCode(options: ExchangeAuthorizationCodeOptions): Promise<OAuthAccessToken>;
+
+interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+/**
+ * Generates a PKCE code verifier and matching S256 challenge per RFC 7636.
+ *
+ * The verifier is 43 base64url characters (32 random bytes encoded). The
+ * challenge is the base64url-encoded SHA-256 hash of the verifier. Use the
+ * challenge in the authorization request and the verifier when exchanging
+ * the resulting code for a token.
+ */
+declare function generatePKCEChallenge(): PKCEChallenge;
+
+export { APIError, AirBase, type AirBaseOptions, AuthenticationError, BadRequestError, type BuildAuthorizationUrlOptions, ConnectionError, CursorPage, type CursorPageParams, type CursorPageResponse, type ExchangeAuthorizationCodeOptions, InternalServerError, NotFoundError, type OAuthAccessToken, type OAuthClientAuthMethod, type PKCEChallenge, PagePromise, PermissionError, RateLimitError, type RequestOptions, TimeoutError, VERSION, buildAuthorizationUrl, exchangeAuthorizationCode, generatePKCEChallenge, getRetryDelay, isRetryableError, retryWithBackoff };

package/dist/index.js

@@ -183,6 +183,7 @@ var VERSION = "0.1.0";
 // src/base-client.ts
 var AirBase = class {
   apiKey;
+  accessToken;
   workspaceId;
   baseURL;
   maxRetries;
@@ -190,19 +191,41 @@ var AirBase = class {
   _fetch;
   _defaultHeaders;
   constructor(options = {}) {
-    const apiKey = options.apiKey ?? process.env.AIR_API_KEY;
-    if (!apiKey) {
+    let apiKey;
+    let accessToken;
+    if (options.apiKey !== void 0 && options.accessToken !== void 0) {
       throw new Error(
-        "API key is required. Pass it as `apiKey` option or set the AIR_API_KEY environment variable."
+        "Provide either `apiKey` or `accessToken`, not both. API key auth and OAuth bearer auth are mutually exclusive."
+      );
+    }
+    if (options.apiKey !== void 0) {
+      apiKey = options.apiKey;
+    } else if (options.accessToken !== void 0) {
+      accessToken = options.accessToken;
+    } else {
+      const envApiKey = process.env.AIR_API_KEY;
+      const envAccessToken = process.env.AIR_ACCESS_TOKEN;
+      if (envApiKey && envAccessToken) {
+        throw new Error(
+          "Both AIR_API_KEY and AIR_ACCESS_TOKEN are set. Set only one, or pass `apiKey`/`accessToken` explicitly to choose."
+        );
+      }
+      apiKey = envApiKey;
+      accessToken = envAccessToken;
+    }
+    if (!apiKey && !accessToken) {
+      throw new Error(
+        "Authentication is required. Pass `apiKey` (or set AIR_API_KEY) for API key auth, or `accessToken` (or set AIR_ACCESS_TOKEN) for OAuth bearer auth."
       );
     }
     const workspaceId = options.workspaceId ?? process.env.AIR_WORKSPACE_ID;
-    if (!workspaceId) {
+    if (apiKey && !workspaceId) {
       throw new Error(
-        "Workspace ID is required. Pass it as `workspaceId` option or set the AIR_WORKSPACE_ID environment variable."
+        "Workspace ID is required when using API key authentication. Pass it as `workspaceId` option or set the AIR_WORKSPACE_ID environment variable."
       );
     }
     this.apiKey = apiKey;
+    this.accessToken = accessToken;
     this.workspaceId = workspaceId;
     this.baseURL = (options.baseURL ?? "https://api.air.inc/v1").replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 3;
@@ -241,12 +264,17 @@ var AirBase = class {
   async _executeRequest(options) {
     const url = this._buildURL(options.path, options.query);
     const headers = {
-      "x-api-key": this.apiKey,
-      "x-air-workspace-id": this.workspaceId,
-      "user-agent": `air-api-sdk/${VERSION}`,
-      ...this._defaultHeaders,
-      ...options.headers
+      "user-agent": `air-api-sdk/${VERSION}`
     };
+    if (this.apiKey) {
+      headers["x-api-key"] = this.apiKey;
+    } else if (this.accessToken) {
+      headers["authorization"] = `Bearer ${this.accessToken}`;
+    }
+    if (this.workspaceId) {
+      headers["x-air-workspace-id"] = this.workspaceId;
+    }
+    Object.assign(headers, this._defaultHeaders, options.headers);
     if (options.body !== void 0) {
       headers["content-type"] = "application/json";
     }
@@ -301,6 +329,90 @@ var AirBase = class {
     return url.toString();
   }
 };
+
+// src/oauth.ts
+function buildAuthorizationUrl(options) {
+  const url = new URL(options.authorizeUrl);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("state", options.state);
+  url.searchParams.set("code_challenge", options.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (options.scopes !== void 0) {
+    const scope = Array.isArray(options.scopes) ? options.scopes.join(" ") : options.scopes;
+    if (scope.length > 0) {
+      url.searchParams.set("scope", scope);
+    }
+  }
+  return url.toString();
+}
+async function exchangeAuthorizationCode(options) {
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: options.code,
+    code_verifier: options.codeVerifier,
+    redirect_uri: options.redirectUri
+  });
+  const headers = {
+    "content-type": "application/x-www-form-urlencoded"
+  };
+  if (options.clientSecret === void 0) {
+    body.set("client_id", options.clientId);
+  } else {
+    applyClientAuth(headers, body, {
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      method: options.clientAuthMethod ?? "basic"
+    });
+  }
+  return executeTokenRequest(fetchFn, options.tokenUrl, headers, body.toString());
+}
+function applyClientAuth(headers, body, args) {
+  if (args.method === "basic") {
+    headers["authorization"] = `Basic ${base64Encode(`${args.clientId}:${args.clientSecret}`)}`;
+  } else {
+    body.set("client_id", args.clientId);
+    body.set("client_secret", args.clientSecret);
+  }
+}
+async function executeTokenRequest(fetchFn, tokenUrl, headers, body) {
+  let response;
+  try {
+    response = await fetchFn(tokenUrl, { method: "POST", headers, body });
+  } catch (error) {
+    throw new ConnectionError(error instanceof Error ? error.message : "Connection failed");
+  }
+  if (!response.ok) {
+    throw await APIError.fromResponse(response);
+  }
+  const raw = await response.json();
+  return {
+    accessToken: raw.access_token,
+    tokenType: raw.token_type,
+    expiresIn: raw.expires_in,
+    scope: raw.scope,
+    refreshToken: raw.refresh_token
+  };
+}
+function base64Encode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf-8").toString("base64");
+  }
+  return btoa(input);
+}
+
+// src/pkce.ts
+import { createHash, randomBytes } from "crypto";
+function generatePKCEChallenge() {
+  const codeVerifier = base64UrlEncode(randomBytes(32));
+  const codeChallenge = base64UrlEncode(createHash("sha256").update(codeVerifier).digest());
+  return { codeVerifier, codeChallenge, codeChallengeMethod: "S256" };
+}
+function base64UrlEncode(input) {
+  return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 export {
   APIError,
   AirBase,
@@ -315,6 +427,9 @@ export {
   RateLimitError,
   TimeoutError,
   VERSION,
+  buildAuthorizationUrl,
+  exchangeAuthorizationCode,
+  generatePKCEChallenge,
   getRetryDelay,
   isRetryableError,
   retryWithBackoff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@air/api-core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Core HTTP engine for Air API SDK",
   "main": "./dist/index.cjs",
@@ -26,7 +26,7 @@
     "build": "tsup",
     "test": "vitest run",
     "typecheck": "tsc -b",
-    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+    "clean": "rm -rf dist .tsc-out tsconfig.tsbuildinfo"
   },
   "engines": {
     "node": ">=18"