WEB SDK Request Layer

SlaunchxFetch is the high-level HTTP client in @slaunchx/web-sdk. It wraps fetch, builds standard headers, retries recoverable failures, refreshes tokens, and can route payloads through Secure Channel for encrypted POST requests.

SlaunchxFetch

Constructor	Description
new SlaunchxFetch(config: FetchConfig)	Requires baseUrl, portalAccessCode, and a shared TokenManager. Optional workspaceId, locale, onTokenExpired, and onError customize behavior.

Standard Requests

get, post, put, and delete all return Promise<ApiResponse<T>>.

import {
  SlaunchxFetch,
  TokenManager,
} from '@slaunchx/web-sdk';

const tokenManager = new TokenManager();

const client = new SlaunchxFetch({
  baseUrl: 'https://api.example.com',
  portalAccessCode: 'portal-web',
  tokenManager,
  locale: 'en',
  workspaceId: 'workspace_123',
  onError: (error) => {
    console.error(error.code, error.httpStatus, error.message);
  },
});

const profile = await client.get<{ id: string; email: string }>('/me');

if (!profile.success) {
  console.error(profile.error.code);
}

Secure Requests

securePost() encrypts the request body through SecureChannel, injects SC headers, and decrypts the response envelope before returning ApiResponse<T>.

const quote = await client.securePost<{ approved: boolean }>(
  '/payments/quote',
  { amount: 100, currency: 'USD' },
);

if (quote.success) {
  console.log(quote.data.approved);
}

HeaderBuilder

HeaderBuilder centralizes the default request headers and can be reused directly when custom transport code still needs SDK-compatible headers.

Header	Added By	Condition
Content-Type: application/json	build()	Always
X-PORTAL-ACCESS-CODE	build()	Always
X-Request-Id	build()	Always, generated as UUID v4
X-LOCALE	build()	Always, defaults to en
X-Workspace-Id	build()	When workspaceId is set
Authorization: Bearer <token>	build()	When a bearer token is supplied
X-SC-Version: 2	buildSecure()	Secure Channel requests only
X-SC-Session-Id	buildSecure()	Secure Channel requests only

import { HeaderBuilder } from '@slaunchx/web-sdk';

const headers = new HeaderBuilder({
  portalAccessCode: 'portal-web',
  locale: 'en',
  workspaceId: 'workspace_123',
}).build('access-token');

RetryPolicy

RetryPolicy is the transport policy behind SlaunchxFetch.

Behavior	Details
First 401	Tries token refresh once, then retries the original request with fresh headers.
Concurrent 401s	Share one in-flight refresh promise.
5xx retry	Retries with exponential backoff: baseDelayMs * 2^attempt, capped by maxDelayMs.
Defaults	maxRetries = 2, baseDelayMs = 500, maxDelayMs = 5000.
No refresh token	Returns the original 401 without refresh.

import { RetryPolicy, TokenManager } from '@slaunchx/web-sdk';

const retryPolicy = new RetryPolicy(
  new TokenManager(),
  async () => {
    console.log('refresh access token');
  },
  { maxRetries: 3, baseDelayMs: 250, maxDelayMs: 2000 },
);

const response = await retryPolicy.execute(() => fetch('https://api.example.com/health'));
console.log(response.status);

ErrorHandler

mapResponseToError(response) converts a failed Response into SdkError.

Input	Output
JSON body matching BackendErrorBody	new SdkError(body.code, body.message, response.status)
Non-JSON or unreadable body	`new SdkError('UNKNOWN_ERROR', response.statusText

PublicErrorCode is the exported enum of public backend error categories: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR, SERVICE_UNAVAILABLE, SESSION_EXPIRED, MFA_REQUIRED, and MFA_INVALID.

import { mapResponseToError } from '@slaunchx/web-sdk';

const response = await fetch('https://api.example.com/me');

if (!response.ok) {
  const error = await mapResponseToError(response);
  console.error(error.code, error.message);
}

Response Shape

All high-level request helpers return ApiResponse<T>.

Field	Type	Meaning
success	boolean	true on success, false on failure
data	T	Present when success is true
error	SdkError	Present when success is false