@oapiex/sdk-kit 0.1.1 → 0.1.3

package/README.md

@@ -1 +1,361 @@
-# SDK Core
+# @oapiex/sdk-kit
+
+[![NPM Downloads](https://img.shields.io/npm/dt/@oapiex/sdk-kit.svg)](https://www.npmjs.com/package/@oapiex/sdk-kit)
+[![npm version](https://img.shields.io/npm/v/@oapiex/sdk-kit.svg)](https://www.npmjs.com/package/@oapiex/sdk-kit)
+[![License](https://img.shields.io/npm/l/@oapiex/sdk-kit.svg)](https://github.com/toneflix/oapiex/blob/main/LICENSE)
+[![codecov](https://img.shields.io/codecov/c/github/toneflix/oapiex.svg?token=9C8arbqlX2)](https://codecov.io/gh/toneflix/oapiex)
+[![Publish Package](https://github.com/toneflix/oapiex/actions/workflows/publish.yml/badge.svg)](https://github.com/toneflix/oapiex/actions/workflows/publish.yml)
+[![Deploy Docs](https://github.com/toneflix/oapiex/actions/workflows/docs.yml/badge.svg)](https://github.com/toneflix/oapiex/actions/workflows/docs.yml)
+[![Run Tests](https://github.com/toneflix/oapiex/actions/workflows/test.yml/badge.svg)](https://github.com/toneflix/oapiex/actions/workflows/test.yml)
+
+Core runtime primitives for SDKs generated by oapiex.
+
+This package provides the shared building blocks used by generated SDK packages:
+
+- `Core` for authenticated SDK instances
+- `BaseApi` for SDK-specific API binders and API classes
+- `createSdk()` for manifest-driven runtime SDKs
+- shared HTTP utilities, exceptions, contracts, and helper types
+
+Most consumers will install a generated SDK package instead of using this package directly. Use `@oapiex/sdk-kit` when you want to build or customize an SDK on top of the generated OpenAPI manifest output.
+
+## Install
+
+```bash
+pnpm add @oapiex/sdk-kit
+```
+
+## Quick Start
+
+### Class-based SDK
+
+```ts
+import { BaseApi, Core, Http } from '@oapiex/sdk-kit';
+
+class ExampleApi extends BaseApi {
+  async list() {
+    await this.core.validateAccess();
+
+    const { data } = await Http.send(
+      this.core.builder.buildTargetUrl('/v1/examples', {}, {}),
+      'GET',
+      {},
+      {},
+    );
+
+    return data;
+  }
+}
+
+class ApiBinder extends BaseApi {
+  examples!: ExampleApi;
+
+  protected override boot() {
+    this.examples = new ExampleApi(this.core);
+  }
+}
+
+class ExampleCore extends Core {
+  static override apiClass = ApiBinder;
+
+  declare api: ApiBinder;
+}
+
+const sdk = new ExampleCore({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  environment: 'sandbox',
+  urls: {
+    sandbox: 'https://sandbox-api.example.com',
+  },
+  headers: {
+    'X-SDK-Version': '1.0.0',
+  },
+  timeout: 10000,
+  auth: {
+    type: 'bearer',
+    token: process.env.ACCESS_TOKEN!,
+  },
+});
+
+await sdk.api.examples.list();
+```
+
+### Runtime manifest SDK
+
+```ts
+import { createSdk, type RuntimeSdkBundle } from '@oapiex/sdk-kit';
+
+const bundle = {
+  document: {},
+  manifest: {
+    groups: [
+      {
+        className: 'Example',
+        propertyName: 'examples',
+        operations: [
+          {
+            path: '/v1/examples',
+            method: 'GET',
+            methodName: 'list',
+            responseType: 'Example[]',
+            inputType: 'Record<string, never>',
+            queryType: 'Record<string, never>',
+            headerType: 'Record<string, never>',
+            paramsType: 'Record<string, never>',
+            hasBody: false,
+            bodyRequired: false,
+            pathParams: [],
+            queryParams: [],
+            headerParams: [],
+          },
+        ],
+      },
+    ],
+  },
+} satisfies RuntimeSdkBundle;
+
+const sdk = createSdk(bundle, {
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  environment: 'sandbox',
+  auth: {
+    type: 'apiKey',
+    name: 'X-API-Key',
+    value: process.env.API_KEY!,
+    in: 'header',
+  },
+});
+
+await sdk.api.examples.list();
+```
+
+## Init Options
+
+`Core` and `createSdk()` both accept the same `InitOptions` object.
+
+- `clientId`: required API client identifier
+- `clientSecret`: required API client secret
+- `environment`: selects `sandbox` or `live`
+- `urls`: optional base URL overrides per environment
+- `headers`: optional default headers added to every request
+- `timeout`: optional Axios timeout in milliseconds
+- `encryptionKey`: optional runtime encryption key override
+- `auth`: one auth strategy or an array of strategies applied to outgoing requests
+
+```ts
+const sdk = new Core({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  environment: 'sandbox',
+  urls: {
+    sandbox: 'https://sandbox-api.example.com',
+    live: 'https://api.example.com',
+  },
+  headers: {
+    'X-Trace-Source': 'example-sdk',
+  },
+  timeout: 15000,
+});
+```
+
+## Auth Shapes
+
+The `auth` option accepts any `AuthConfig` supported by the transport layer.
+
+### Bearer
+
+```ts
+auth: {
+  type: 'bearer',
+  token: process.env.ACCESS_TOKEN!,
+}
+```
+
+### Basic
+
+```ts
+auth: {
+  type: 'basic',
+  username: process.env.API_USERNAME!,
+  password: process.env.API_PASSWORD!,
+}
+```
+
+### API Key
+
+```ts
+auth: {
+  type: 'apiKey',
+  name: 'X-API-Key',
+  value: process.env.API_KEY!,
+  in: 'header',
+}
+```
+
+### OAuth2 Token
+
+```ts
+auth: {
+  type: 'oauth2',
+  accessToken: process.env.ACCESS_TOKEN!,
+  tokenType: 'Bearer',
+}
+```
+
+### Multiple Strategies
+
+```ts
+auth: [
+  {
+    type: 'apiKey',
+    name: 'X-Partner-Key',
+    value: process.env.PARTNER_KEY!,
+    in: 'header',
+  },
+  {
+    type: 'apiKey',
+    name: 'api_key',
+    value: process.env.QUERY_KEY!,
+    in: 'query',
+  },
+];
+```
+
+### Custom
+
+```ts
+auth: {
+  type: 'custom',
+  apply: async (request) => ({
+    ...request,
+    headers: {
+      ...request.headers,
+      Authorization: `Token ${process.env.CUSTOM_TOKEN!}`,
+    },
+  }),
+}
+```
+
+Generated SDK packages can now expose auth helper functions derived from OpenAPI `securitySchemes`, plus `securitySchemes` and `security` metadata exports for inspection.
+
+## Access Validator Auth Refresh
+
+`setAccessValidator()` can be used to replace auth before the actual SDK request is sent. This is useful for APIs like Flutterwave where you first exchange API keys for a bearer token.
+
+The validator can:
+
+- return `true` to allow the request as-is
+- return a string to fail validation with a custom message
+- return an `AuthConfig` or `AuthConfig[]` to replace auth for the pending request
+- return a partial config object such as `{ auth, headers, timeout }`
+- call `core.setAuth(...)` or `core.configure(...)` directly
+
+```ts
+import axios from 'axios';
+import { Core } from '@oapiex/sdk-kit';
+
+const sdk = new Core({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  environment: 'sandbox',
+  urls: {
+    sandbox: 'https://developersandbox-api.example.com',
+  },
+});
+
+sdk.setAccessValidator(async (core) => {
+  const response = await axios.post(
+    'https://developersandbox-api.example.com/auth/token',
+    {
+      client_id: core.getClientId(),
+      client_secret: core.getClientSecret(),
+    },
+  );
+
+  return {
+    type: 'bearer',
+    token: response.data.access_token,
+  };
+});
+
+await sdk.api.examples.list();
+```
+
+If you need to update more than auth, return a config object instead:
+
+```ts
+sdk.setAccessValidator(async (core) => {
+  const response = await axios.post(
+    'https://developersandbox-api.example.com/auth/token',
+    {
+      client_id: core.getClientId(),
+      client_secret: core.getClientSecret(),
+    },
+  );
+
+  return {
+    auth: {
+      type: 'bearer',
+      token: response.data.access_token,
+    },
+    headers: {
+      'X-Token-Source': 'access-validator',
+    },
+  };
+});
+```
+
+If the token endpoint returns an expiry value, use `createAccessTokenCache()` so the validator does not fetch a new token on every request.
+
+```ts
+import axios from 'axios';
+import { Core, createAccessTokenCache } from '@oapiex/sdk-kit';
+
+const sdk = new Core({
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  environment: 'sandbox',
+  urls: {
+    sandbox: 'https://developersandbox-api.example.com',
+  },
+});
+
+const tokenCache = createAccessTokenCache(async (core) => {
+  const response = await axios.post(
+    'https://developersandbox-api.example.com/auth/token',
+    {
+      client_id: core.getClientId(),
+      client_secret: core.getClientSecret(),
+    },
+  );
+
+  return {
+    token: response.data.access_token,
+    expiresInSeconds: Math.max((response.data.expires_in ?? 60) - 30, 1),
+  };
+});
+
+sdk.setAccessValidator(tokenCache);
+```
+
+## Main Exports
+
+- `Core`: base SDK client with environment setup, access validation, and runtime bundle support
+- `BaseApi`: base class for SDK-specific API binders and API classes
+- `createSdk()`: helper for creating a runtime SDK from a manifest bundle
+- `AuthConfig`: shared auth strategy union used by `InitOptions.auth`
+- `createAccessTokenCache()`: helper for caching validator-fetched tokens until expiry
+- `setAccessValidator()`: hook for readiness checks, auth refresh, and config replacement before requests
+- `Http`, `Builder`, and exceptions: lower-level request and error primitives
+- `InitOptions`, `UnifiedResponse`, and runtime manifest types: shared contracts for generated SDKs
+
+## Commands
+
+Run these inside `packages/sdk-kit`:
+
+```bash
+pnpm test
+pnpm build
+pnpm coverage
+```

package/dist/contracts.d.cts

@@ -1,2 +1,2 @@
-import { _ as CountryCodeRestricted, a as InitOptions, c as Response, d as UnifiedResponse, f as UserConfig, g as CountryCode, h as XGenericObject, i as ErrorResponse, l as ResponseStatus, m as ValidationErrorResponse, n as AuthResponse, o as NormalPagination, p as ValidationError, r as CursorPagination, s as PageInfoMeta, t as AuthErrorResponse, u as SuccessResponse, v as CurrencyCode } from "./index-BYtse_Mh.cjs";
-export { AuthErrorResponse, AuthResponse, CountryCode, CountryCodeRestricted, CurrencyCode, CursorPagination, ErrorResponse, InitOptions, NormalPagination, PageInfoMeta, Response, ResponseStatus, SuccessResponse, UnifiedResponse, UserConfig, ValidationError, ValidationErrorResponse, XGenericObject };
+import { A as CurrencyCode, C as UserConfig, D as XGenericObject, E as ValidationErrorResponse, O as CountryCode, S as UnifiedResponse, T as ValidationError, _ as OAuth2AuthConfig, a as AuthErrorResponse, b as ResponseStatus, c as BasicAuthConfig, d as CustomAuthConfig, f as Environment, g as NormalPagination, h as InitOptions, i as AuthConfig, k as CountryCodeRestricted, l as BearerAuthConfig, m as HttpMethod, n as AccessValidationResult, o as AuthRequestConfig, p as ErrorResponse, r as ApiKeyAuthConfig, s as AuthResponse, t as AccessValidationConfigUpdate, u as CursorPagination, v as PageInfoMeta, w as UserUrls, x as SuccessResponse, y as Response } from "./index-JjhthUpt.cjs";
+export { AccessValidationConfigUpdate, AccessValidationResult, ApiKeyAuthConfig, AuthConfig, AuthErrorResponse, AuthRequestConfig, AuthResponse, BasicAuthConfig, BearerAuthConfig, CountryCode, CountryCodeRestricted, CurrencyCode, CursorPagination, CustomAuthConfig, Environment, ErrorResponse, HttpMethod, InitOptions, NormalPagination, OAuth2AuthConfig, PageInfoMeta, Response, ResponseStatus, SuccessResponse, UnifiedResponse, UserConfig, UserUrls, ValidationError, ValidationErrorResponse, XGenericObject };

package/dist/contracts.d.ts

@@ -1,2 +1,2 @@
-import { _ as CountryCodeRestricted, a as InitOptions, c as Response, d as UnifiedResponse, f as UserConfig, g as CountryCode, h as XGenericObject, i as ErrorResponse, l as ResponseStatus, m as ValidationErrorResponse, n as AuthResponse, o as NormalPagination, p as ValidationError, r as CursorPagination, s as PageInfoMeta, t as AuthErrorResponse, u as SuccessResponse, v as CurrencyCode } from "./index-sMTTpEJS.js";
-export { AuthErrorResponse, AuthResponse, CountryCode, CountryCodeRestricted, CurrencyCode, CursorPagination, ErrorResponse, InitOptions, NormalPagination, PageInfoMeta, Response, ResponseStatus, SuccessResponse, UnifiedResponse, UserConfig, ValidationError, ValidationErrorResponse, XGenericObject };
+import { A as CurrencyCode, C as UserConfig, D as XGenericObject, E as ValidationErrorResponse, O as CountryCode, S as UnifiedResponse, T as ValidationError, _ as OAuth2AuthConfig, a as AuthErrorResponse, b as ResponseStatus, c as BasicAuthConfig, d as CustomAuthConfig, f as Environment, g as NormalPagination, h as InitOptions, i as AuthConfig, k as CountryCodeRestricted, l as BearerAuthConfig, m as HttpMethod, n as AccessValidationResult, o as AuthRequestConfig, p as ErrorResponse, r as ApiKeyAuthConfig, s as AuthResponse, t as AccessValidationConfigUpdate, u as CursorPagination, v as PageInfoMeta, w as UserUrls, x as SuccessResponse, y as Response } from "./index-DUI9uPJQ.js";
+export { AccessValidationConfigUpdate, AccessValidationResult, ApiKeyAuthConfig, AuthConfig, AuthErrorResponse, AuthRequestConfig, AuthResponse, BasicAuthConfig, BearerAuthConfig, CountryCode, CountryCodeRestricted, CurrencyCode, CursorPagination, CustomAuthConfig, Environment, ErrorResponse, HttpMethod, InitOptions, NormalPagination, OAuth2AuthConfig, PageInfoMeta, Response, ResponseStatus, SuccessResponse, UnifiedResponse, UserConfig, UserUrls, ValidationError, ValidationErrorResponse, XGenericObject };

package/dist/{index-BYtse_Mh.d.cts → index-DUI9uPJQ.d.ts}

@@ -9,6 +9,8 @@ interface XGenericObject {
 }
 //#endregion
 //#region src/Contracts/Core.d.ts
+type Environment = 'sandbox' | 'live';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type ResponseStatus = 'failed' | 'success';
 interface ValidationError {
   'field_name': string;
@@ -78,30 +80,87 @@ interface NormalPagination {
 interface PageInfoMeta {
   page_info: NormalPagination;
 }
+interface UserUrls {
+  live?: string;
+  sandbox?: string;
+}
+interface BearerAuthConfig {
+  type: 'bearer';
+  token: string;
+  prefix?: string;
+}
+interface OAuth2AuthConfig {
+  type: 'oauth2';
+  accessToken: string;
+  tokenType?: string;
+}
+interface BasicAuthConfig {
+  type: 'basic';
+  username: string;
+  password: string;
+}
+interface ApiKeyAuthConfig {
+  type: 'apiKey';
+  name: string;
+  value: string;
+  in?: 'header' | 'query' | 'cookie';
+  prefix?: string;
+}
+interface AuthRequestConfig {
+  url: string;
+  method: HttpMethod;
+  headers: Record<string, string>;
+  params: XGenericObject;
+  body?: unknown;
+}
+interface CustomAuthConfig {
+  type: 'custom';
+  apply: (request: AuthRequestConfig) => AuthRequestConfig | Promise<AuthRequestConfig>;
+}
+type AuthConfig = BearerAuthConfig | OAuth2AuthConfig | BasicAuthConfig | ApiKeyAuthConfig | CustomAuthConfig;
+type AccessValidationConfigUpdate = Partial<UserConfig> | AuthConfig | AuthConfig[];
+type AccessValidationResult = boolean | string | void | AccessValidationConfigUpdate;
 interface InitOptions {
   /**
-   * Your Flutterwave Public Key
+   * Your API Public Key
    */
   clientId: string;
   /**
-   * Your Flutterwave Secret Key
+   * Your API Secret Key
    */
   clientSecret: string;
   /**
-   * Your Flutterwave Encryption Key
+   * Your API Encryption Key
    */
   encryptionKey?: string;
   /**
    * Environment to use
    */
-  environment?: 'sandbox' | 'live';
+  environment?: Environment;
+  /**
+   * Override environment base URLs.
+   */
+  urls?: UserUrls;
+  /**
+   * Default headers applied to every request.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout?: number;
+  /**
+   * Request authentication strategy or strategies.
+   */
+  auth?: AuthConfig | AuthConfig[];
 }
 interface UserConfig {
-  environment?: 'sandbox' | 'live';
-  urls: {
-    live: string;
-    sandbox: string;
-  };
+  environment?: Environment;
+  urls?: UserUrls;
+  headers?: Record<string, string>;
+  timeout?: number;
+  encryptionKey?: string;
+  auth?: AuthConfig | AuthConfig[];
 }
 //#endregion
-export { CountryCodeRestricted as _, InitOptions as a, Response as c, UnifiedResponse as d, UserConfig as f, CountryCode as g, XGenericObject as h, ErrorResponse as i, ResponseStatus as l, ValidationErrorResponse as m, AuthResponse as n, NormalPagination as o, ValidationError as p, CursorPagination as r, PageInfoMeta as s, AuthErrorResponse as t, SuccessResponse as u, CurrencyCode as v };
+export { CurrencyCode as A, UserConfig as C, XGenericObject as D, ValidationErrorResponse as E, CountryCode as O, UnifiedResponse as S, ValidationError as T, OAuth2AuthConfig as _, AuthErrorResponse as a, ResponseStatus as b, BasicAuthConfig as c, CustomAuthConfig as d, Environment as f, NormalPagination as g, InitOptions as h, AuthConfig as i, CountryCodeRestricted as k, BearerAuthConfig as l, HttpMethod as m, AccessValidationResult as n, AuthRequestConfig as o, ErrorResponse as p, ApiKeyAuthConfig as r, AuthResponse as s, AccessValidationConfigUpdate as t, CursorPagination as u, PageInfoMeta as v, UserUrls as w, SuccessResponse as x, Response as y };

package/dist/{index-sMTTpEJS.d.ts → index-JjhthUpt.d.cts}

@@ -9,6 +9,8 @@ interface XGenericObject {
 }
 //#endregion
 //#region src/Contracts/Core.d.ts
+type Environment = 'sandbox' | 'live';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 type ResponseStatus = 'failed' | 'success';
 interface ValidationError {
   'field_name': string;
@@ -78,30 +80,87 @@ interface NormalPagination {
 interface PageInfoMeta {
   page_info: NormalPagination;
 }
+interface UserUrls {
+  live?: string;
+  sandbox?: string;
+}
+interface BearerAuthConfig {
+  type: 'bearer';
+  token: string;
+  prefix?: string;
+}
+interface OAuth2AuthConfig {
+  type: 'oauth2';
+  accessToken: string;
+  tokenType?: string;
+}
+interface BasicAuthConfig {
+  type: 'basic';
+  username: string;
+  password: string;
+}
+interface ApiKeyAuthConfig {
+  type: 'apiKey';
+  name: string;
+  value: string;
+  in?: 'header' | 'query' | 'cookie';
+  prefix?: string;
+}
+interface AuthRequestConfig {
+  url: string;
+  method: HttpMethod;
+  headers: Record<string, string>;
+  params: XGenericObject;
+  body?: unknown;
+}
+interface CustomAuthConfig {
+  type: 'custom';
+  apply: (request: AuthRequestConfig) => AuthRequestConfig | Promise<AuthRequestConfig>;
+}
+type AuthConfig = BearerAuthConfig | OAuth2AuthConfig | BasicAuthConfig | ApiKeyAuthConfig | CustomAuthConfig;
+type AccessValidationConfigUpdate = Partial<UserConfig> | AuthConfig | AuthConfig[];
+type AccessValidationResult = boolean | string | void | AccessValidationConfigUpdate;
 interface InitOptions {
   /**
-   * Your Flutterwave Public Key
+   * Your API Public Key
    */
   clientId: string;
   /**
-   * Your Flutterwave Secret Key
+   * Your API Secret Key
    */
   clientSecret: string;
   /**
-   * Your Flutterwave Encryption Key
+   * Your API Encryption Key
    */
   encryptionKey?: string;
   /**
    * Environment to use
    */
-  environment?: 'sandbox' | 'live';
+  environment?: Environment;
+  /**
+   * Override environment base URLs.
+   */
+  urls?: UserUrls;
+  /**
+   * Default headers applied to every request.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout?: number;
+  /**
+   * Request authentication strategy or strategies.
+   */
+  auth?: AuthConfig | AuthConfig[];
 }
 interface UserConfig {
-  environment?: 'sandbox' | 'live';
-  urls: {
-    live: string;
-    sandbox: string;
-  };
+  environment?: Environment;
+  urls?: UserUrls;
+  headers?: Record<string, string>;
+  timeout?: number;
+  encryptionKey?: string;
+  auth?: AuthConfig | AuthConfig[];
 }
 //#endregion
-export { CountryCodeRestricted as _, InitOptions as a, Response as c, UnifiedResponse as d, UserConfig as f, CountryCode as g, XGenericObject as h, ErrorResponse as i, ResponseStatus as l, ValidationErrorResponse as m, AuthResponse as n, NormalPagination as o, ValidationError as p, CursorPagination as r, PageInfoMeta as s, AuthErrorResponse as t, SuccessResponse as u, CurrencyCode as v };
+export { CurrencyCode as A, UserConfig as C, XGenericObject as D, ValidationErrorResponse as E, CountryCode as O, UnifiedResponse as S, ValidationError as T, OAuth2AuthConfig as _, AuthErrorResponse as a, ResponseStatus as b, BasicAuthConfig as c, CustomAuthConfig as d, Environment as f, NormalPagination as g, InitOptions as h, AuthConfig as i, CountryCodeRestricted as k, BearerAuthConfig as l, HttpMethod as m, AccessValidationResult as n, AuthRequestConfig as o, ErrorResponse as p, ApiKeyAuthConfig as r, AuthResponse as s, AccessValidationConfigUpdate as t, CursorPagination as u, PageInfoMeta as v, UserUrls as w, SuccessResponse as x, Response as y };