WEB SDK API Reference

This page documents the public exports from @slaunchx/web-sdk as defined by src/index.ts.

Secure Channel

SecureChannel

Item	Signature	Description
Constructor	new SecureChannel(baseUrl: string, portalAccessCode: string)	Create a Secure Channel client bound to an SC base URL and portal access code.
Method	initSession(): Promise<void>	Fetch the RSA public key, create AES request/response keys, and establish a session.
Method	encrypt(data: unknown): Promise<string>	JSON-serialize and encrypt a request payload into an SCv2 envelope string.
Method	decrypt(envelope: string): Promise<unknown>	Decrypt an SCv2 response envelope and parse the JSON payload.
Method	isSessionActive(): boolean	Return true when a session exists and has not expired.
Method	getSessionId(): string | null	Return the active session id, or null if none exists.

RsaPublicKeyInfo

Field	Type	Description
keyId	string	Backend key identifier used during session creation.
publicKey	string	Base64-encoded SPKI DER RSA public key.
algorithm	string	Algorithm metadata returned by the backend.
keySize	number	RSA key size in bits.
createdAt	string	Backend creation timestamp.
expiresAt	string	Backend expiry timestamp.

SecureChannelSession

Field	Type	Description
sessionId	string	Active Secure Channel session id.
requestKey	CryptoKey	AES key used for request encryption.
responseKey	CryptoKey	AES key used for response decryption.
expiresAt	number	Expiry timestamp in milliseconds.

Envelope Functions

Function	Signature	Description
encodeEnvelope	encodeEnvelope(plaintext: Uint8Array, aesKey: CryptoKey, sessionId?: string): Promise<string>	Encrypt plaintext bytes into a JSON envelope string.
decodeEnvelope	decodeEnvelope(envelope: string, aesKey: CryptoKey, sessionId?: string): Promise<Uint8Array>	Parse and decrypt a JSON envelope string.

Crypto Functions

Function	Signature	Description
generateAesKey	generateAesKey(): Promise<Uint8Array>	Generate a raw 32-byte AES-256 key.
importAesKey	importAesKey(raw: Uint8Array): Promise<CryptoKey>	Import raw AES bytes into a Web Crypto CryptoKey.
aesGcmEncrypt	aesGcmEncrypt(key: CryptoKey, plaintext: Uint8Array, iv: Uint8Array, aad?: Uint8Array): Promise<{ ciphertext: Uint8Array; tag: Uint8Array }>	Encrypt bytes with AES-256-GCM.
aesGcmDecrypt	aesGcmDecrypt(key: CryptoKey, ciphertext: Uint8Array, iv: Uint8Array, tag: Uint8Array, aad?: Uint8Array): Promise<Uint8Array>	Decrypt AES-256-GCM bytes.
rsaOaepEncrypt	rsaOaepEncrypt(publicKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>	Encrypt bytes with an RSA-OAEP public key.
importRsaPublicKey	importRsaPublicKey(spkiDer: Uint8Array): Promise<CryptoKey>	Import an SPKI DER RSA public key configured for RSA-OAEP SHA-256.
randomBytes	randomBytes(n: number): Uint8Array	Generate cryptographically random bytes.

Utility Functions

Function	Signature	Description
toBase64Url	toBase64Url(bytes: Uint8Array): string	Encode bytes to Base64URL without padding.
fromBase64Url	fromBase64Url(str: string): Uint8Array	Decode a Base64URL string into bytes.
toBase64	toBase64(bytes: Uint8Array): string	Encode bytes to standard Base64 with padding.
fromBase64	fromBase64(str: string): Uint8Array	Decode a standard Base64 string into bytes.
buildAad	buildAad(sessionId: string, direction: 'request' | 'response'): Uint8Array	Build SCv2 additional authenticated data bytes.

Auth

AuthClient

Item	Signature	Description
Constructor	new AuthClient(config: AuthClientConfig)	Create an auth client bound to a shared TokenManager.
Method	initiateLogin(username: string, password: string): Promise<MfaChallenge>	Submit credentials and receive the MFA challenge.
Method	completeLogin(sessionId: string, method: string, code: string): Promise<void>	Complete MFA, store the returned TokenPair, and set the state to authenticated.
Method	refreshToken(): Promise<void>	Use the stored refresh token to obtain a new TokenPair.
Method	logout(): Promise<void>	Best-effort server logout followed by local state cleanup.
Method	getState(): AuthState	Return the current auth state.

AuthClientConfig

Field	Type	Description
baseUrl	string	API base URL.
portalAccessCode	string	Value for X-PORTAL-ACCESS-CODE.
tokenManager	TokenManager	Shared token storage for auth and request clients.

TokenManager

Item	Signature	Description
Constructor	new TokenManager()	Create an in-memory token store.
Method	setTokens(pair: TokenPair): void	Store access token, refresh token, and computed expiry time.
Method	getAccessToken(): string | null	Return the current access token.
Method	getRefreshToken(): string | null	Return the current refresh token.
Method	isExpired(): boolean	Return true when no token exists or it is expired.
Method	clear(): void	Remove all stored token state.

MfaHandler

Item	Signature	Description
Constructor	new MfaHandler()	Create a standalone MFA challenge helper.
Method	setChallenge(challenge: MfaChallenge): void	Store the active challenge.
Method	getAvailableMethods(): MfaMethod[]	Return the allowed MFA methods.
Method	getSessionId(): string | null	Return the active MFA session id.
Method	isExpired(): boolean	Check whether the challenge is missing or expired.
Method	clear(): void	Clear the active challenge.
Method	prepareVerification(method: MfaMethod, code: string): { sessionId: string; method: MfaMethod; code: string } | null	Build the verification payload for a valid method.

Auth Types

AuthState

Variant
'unauthenticated'
'mfa_pending'
'authenticated'

MfaMethod

Variant
'EMAIL'
'TOTP'
'SMS'

MfaChallenge

Field	Type	Description
sessionId	string	Challenge session id used in login completion.
methods	MfaMethod[]	Allowed MFA methods.
expiresAt	number	Expiry timestamp in milliseconds.

LoginResult

Field	Type	Description
accessToken	string	Access token.
refreshToken	string	Refresh token.
expiresIn	number	Access token lifetime in seconds.

TokenPair

Field	Type	Description
accessToken	string	Access token.
refreshToken	string	Refresh token.
expiresIn	number	Access token lifetime in seconds.

Request

SlaunchxFetch

Item	Signature	Description
Constructor	new SlaunchxFetch(config: FetchConfig)	Create a request client with standard headers, retry, and Secure Channel support.
Method	setWorkspaceId(id: string): void	Update the workspace header for subsequent requests.
Method	get<T>(path: string, params?: Record<string, string>): Promise<ApiResponse<T>>	Perform a GET request.
Method	post<T>(path: string, body?: unknown): Promise<ApiResponse<T>>	Perform a POST request.
Method	put<T>(path: string, body?: unknown): Promise<ApiResponse<T>>	Perform a PUT request.
Method	delete<T>(path: string, body?: unknown): Promise<ApiResponse<T>>	Perform a DELETE request.
Method	securePost<T>(path: string, body: unknown): Promise<ApiResponse<T>>	Perform an encrypted POST request over Secure Channel.

FetchConfig

Field	Type	Description
baseUrl	string	API base URL.
portalAccessCode	string	Value for X-PORTAL-ACCESS-CODE.
tokenManager	TokenManager	Shared token storage.
workspaceId	string	Optional workspace header value.
locale	string	Optional locale header value. Defaults to en in HeaderBuilder.
onTokenExpired	() => void	Optional callback when a normal request still ends in 401.
onError	(error: SdkError) => void	Optional callback for non-401 request errors and secure request errors.

HeaderBuilder

Item	Signature	Description
Constructor	new HeaderBuilder(config: HeaderBuilderConfig)	Create a reusable header builder.
Method	setWorkspaceId(id: string): void	Update the workspace header for future builds.
Method	build(bearerToken?: string | null): Record<string, string>	Build standard SDK headers.
Method	buildSecure(scSessionId: string, bearerToken?: string | null): Record<string, string>	Build standard headers plus SC headers.

HeaderBuilderConfig

Field	Type	Description
portalAccessCode	string	Required portal access code.
locale	string	Optional locale. Defaults to en.
workspaceId	string	Optional workspace id.
scVersion	number	Declared in the type but not used by the current implementation.
scSessionId	string	Declared in the type but not used by the current implementation.

RetryPolicy

Item	Signature	Description
Constructor	new RetryPolicy(tokenManager: TokenManager, refreshFn: () => Promise<void>, config?: RetryConfig)	Create a retry policy with optional backoff settings.
Method	execute(doRequest: () => Promise<Response>): Promise<Response>	Execute a request with 401 refresh handling and 5xx retry.

RetryConfig

Field	Type	Description
maxRetries	number	Maximum number of retry rounds for 5xx responses. Default 2.
baseDelayMs	number	Base backoff delay in milliseconds. Default 500.
maxDelayMs	number	Maximum backoff delay in milliseconds. Default 5000.

Error Handling

mapResponseToError

Function	Signature	Description
mapResponseToError	mapResponseToError(response: Response): Promise<SdkError>	Convert a failed Response into SdkError.

BackendErrorBody

Field	Type	Description
code	string	Backend error code.
message	string	Backend error message.

PublicErrorCode

Variant
UNAUTHORIZED
FORBIDDEN
NOT_FOUND
VALIDATION_ERROR
RATE_LIMITED
INTERNAL_ERROR
SERVICE_UNAVAILABLE
SESSION_EXPIRED
MFA_REQUIRED
MFA_INVALID

Shared Types

SdkError

Item	Signature	Description
Constructor	new SdkError(code: string, message: string, httpStatus?: number)	Create a typed SDK error.
Property	code: string	Structured error code.
Property	httpStatus?: number	Optional HTTP status from the failed response.

ApiResponse<T>

Field	Type	Description
success	boolean	Indicates whether the request succeeded.
data	T	Present on success.
error	SdkError	Present on failure.