Documentation Index
Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
Use this file to discover all available pages before exploring further.
All Amplify SDK functions require initialization before use. Call initAmplifySDK() once at application startup.
initAmplifySDK()
import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
await initAmplifySDK("pxl_your_api_key");
Function Signature
export async function initAmplifySDK(
apiKey: string,
options?: SDKInitOptions
): Promise<void>;
Parameters
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Your Paxos Labs API key (format: pxl_...) |
options | SDKInitOptions | No | Configuration options for telemetry and logging |
SDKInitOptions
export interface SDKInitOptions {
/** Enable/disable PostHog telemetry (default: true) */
telemetry?: boolean;
/** Log level for SDK operations (default: LogLevel.ERROR) */
logLevel?: LogLevel;
/** Custom logger implementation */
logger?: Logger;
}
| Option | Type | Default | Description |
|---|
telemetry | boolean | true | Enable PostHog error tracking |
logLevel | LogLevel | LogLevel.ERROR | Minimum log level to output |
logger | Logger | Built-in console logger | Custom logger implementation |
Usage Examples
Basic Initialization
import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
// Initialize with just the API key
await initAmplifySDK("pxl_your_api_key");
With Telemetry Disabled
import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
await initAmplifySDK("pxl_your_api_key", {
telemetry: false,
});
With Debug Logging
import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";
await initAmplifySDK("pxl_your_api_key", {
logLevel: LogLevel.DEBUG,
});
With All Options
import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";
await initAmplifySDK("pxl_your_api_key", {
telemetry: false,
logLevel: LogLevel.DEBUG,
logger: {
debug: (msg, ctx) => console.debug(`[SDK] ${msg}`, ctx),
info: (msg, ctx) => console.info(`[SDK] ${msg}`, ctx),
warn: (msg, ctx) => console.warn(`[SDK] ${msg}`, ctx),
error: (msg, ctx) => console.error(`[SDK] ${msg}`, ctx),
},
});
React Integration
Create a hook to initialize the SDK once and expose ready state:
// src/hooks/useAmplify.ts
import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
import { useEffect, useState } from "react";
let initialized = false;
export function useAmplify() {
const [isReady, setIsReady] = useState(initialized);
const [error, setError] = useState<Error | null>(null);
useEffect(() => {
if (initialized) {
setIsReady(true);
return;
}
const apiKey = import.meta.env.VITE_AMPLIFY_API_KEY;
if (!apiKey) {
setError(new Error("Missing VITE_AMPLIFY_API_KEY env variable"));
return;
}
async function init() {
try {
await initAmplifySDK(apiKey);
initialized = true;
setIsReady(true);
} catch (err) {
setError(err instanceof Error ? err : new Error("SDK initialization failed"));
}
}
init();
}, []);
return { isReady, error };
}
// src/App.tsx
import { useAmplify } from "./hooks/useAmplify";
export function App() {
const { isReady, error } = useAmplify();
if (error) {
return <div>Failed to initialize SDK: {error.message}</div>;
}
if (!isReady) {
return <div>Initializing...</div>;
}
return <YourApp />;
}
Behavior
- Validates API key - Ensures key follows expected format
- Pre-populates cache - Fetches vaults and assets during initialization
- Configures telemetry - Sets up PostHog if enabled
- Configures logging - Sets log level and optional custom logger
- Idempotent - Multiple calls with same key are no-ops
- Re-initialization - Different key clears cache and reconfigures
Error Handling
try {
await initAmplifySDK("pxl_your_api_key");
} catch (error) {
if (error.code === "INVALID_API_KEY") {
console.error("Invalid API key format");
}
}
| Error Code | Description | Resolution |
|---|
SDK_NOT_INITIALIZED | SDK used before initAmplifySDK() | Call initAmplifySDK() first |
INVALID_API_KEY | API key validation failed | Check API key format |
