@aurelo_npm/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+export type AureloJson = null | boolean | number | string | AureloJson[] | {
+    [key: string]: AureloJson;
+};
+export interface AureloStorage {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    delete?(key: string): void | Promise<void>;
+}
+export interface AureloSDKOptions {
+    apiKey: string;
+    baseUrl?: string;
+    queueUrl?: string;
+    clientId?: string;
+    storage?: AureloStorage;
+    fetch?: typeof fetch;
+}
+export interface AureloSessionManagerOptions {
+    clientId?: string;
+    storage?: AureloStorage;
+}
+export interface AureloSession {
+    clientId: string;
+    requestId: string;
+    sessionId: string;
+    createdAt: number;
+    status: 'active' | 'closed' | 'rotation_required';
+    rotationReason?: string;
+}
+export interface AureloResponseRequest {
+    model: string;
+    input?: unknown;
+    stream?: boolean;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface AureloReconnectRequest {
+    sessionId?: string;
+    cursor?: string | number;
+    model?: string;
+    input?: unknown;
+    signal?: AbortSignal;
+}
+export interface AureloQueueMessageRequest {
+    message: string;
+    sessionId?: string;
+    source?: string;
+    requestId?: string;
+    publicModel?: string;
+    model?: string;
+    metadata?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface AureloStreamEvent {
+    type: 'comment' | 'event' | 'done';
+    raw: string;
+    comment?: string;
+    data?: unknown;
+}
+export declare class AureloSDKError extends Error {
+    status: number;
+    reason: string;
+    rotateSession: boolean;
+    payload: unknown;
+    constructor(message: string, options: {
+        status: number;
+        reason?: string;
+        rotateSession?: boolean;
+        payload?: unknown;
+    });
+}
+export declare function createAureloClientId(): string;
+export declare function normalizeAureloClientId(value: string): string;
+export declare function getAureloFullClientId(clientId: string): string;
+export declare function createAureloRequestId(): string;
+export declare function createAureloSession(clientId: string): AureloSession;
+export declare class AureloSessionManager {
+    private readonly storage;
+    private clientIdValue;
+    private sessionValue;
+    constructor(options?: AureloSessionManagerOptions);
+    getClientId(): Promise<string>;
+    getFullClientId(): Promise<string>;
+    getSession(): Promise<AureloSession>;
+    private getStoredActiveSession;
+    rotateSession(reason?: string): Promise<AureloSession>;
+    closeSession(reason?: string): Promise<void>;
+}
+export declare class AureloSDK {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly queueUrl;
+    private readonly fetchImpl;
+    private readonly storage;
+    private clientIdValue;
+    private sessionValue;
+    private reconnectCursors;
+    constructor(options: AureloSDKOptions);
+    getClientId(): Promise<string>;
+    getFullClientId(): Promise<string>;
+    getSession(): Promise<AureloSession>;
+    private getStoredActiveSession;
+    rotateSession(reason?: string): Promise<AureloSession>;
+    closeSession(reason?: string): Promise<void>;
+    private markSessionClosed;
+    private getReconnectCursor;
+    private setReconnectCursor;
+    private clearReconnectCursor;
+    observeSseComment(comment: string): Promise<void>;
+    queueMessage(request: string | AureloQueueMessageRequest): Promise<unknown>;
+    createResponse(request: AureloResponseRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    private createResponseWithRotationRetry;
+    createOrContinueResponse(request: AureloResponseRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    streamResponse(request: AureloResponseRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<AureloStreamEvent>;
+    streamReconnect(request?: AureloReconnectRequest): AsyncGenerator<AureloStreamEvent>;
+    continueResponse(message: string, request?: Omit<AureloQueueMessageRequest, 'message'> & AureloReconnectRequest): AsyncGenerator<AureloStreamEvent>;
+    private streamEventsFromResponse;
+    reconnect(request?: AureloReconnectRequest): Promise<Response>;
+    private handleSseLine;
+    private readErrorPayload;
+    private readResponsePayload;
+}
+export default AureloSDK;

package/dist/index.js

@@ -0,0 +1,727 @@
+export class AureloSDKError extends Error {
+    status;
+    reason;
+    rotateSession;
+    payload;
+    constructor(message, options) {
+        super(message);
+        this.name = 'AureloSDKError';
+        this.status = options.status;
+        this.reason = options.reason || '';
+        this.rotateSession = !!options.rotateSession;
+        this.payload = options.payload;
+    }
+}
+const CLIENT_ID_KEY = 'aurelo.sdk.clientId';
+const SESSION_KEY = 'aurelo.sdk.session';
+const RECONNECT_CURSOR_KEY_PREFIX = 'aurelo.sdk.reconnectCursor.';
+const ROTATION_REASONS = new Set([
+    'input_threshold_reached',
+    'output_threshold_reached',
+    'no_active_runtime',
+    'no_active_reconnect_stream',
+    'window_expired',
+    'loop_rollover_pending',
+    'request_closed',
+    'response_completed',
+    'response_done',
+    'tracked_user_mismatch',
+]);
+class MemoryStorage {
+    values = new Map();
+    get(key) {
+        return this.values.get(key) || null;
+    }
+    set(key, value) {
+        this.values.set(key, value);
+    }
+    delete(key) {
+        this.values.delete(key);
+    }
+}
+function createDefaultStorage() {
+    const localStorageRef = globalThis.localStorage;
+    if (localStorageRef) {
+        return {
+            get: (key) => localStorageRef.getItem(key),
+            set: (key, value) => localStorageRef.setItem(key, value),
+            delete: (key) => localStorageRef.removeItem(key),
+        };
+    }
+    return new MemoryStorage();
+}
+function normalizeBaseUrl(value) {
+    return String(value || '').trim().replace(/\/+$/, '') || 'https://aurelo.tech';
+}
+function defaultQueueUrl(baseUrl) {
+    try {
+        const parsed = new URL(baseUrl);
+        if (parsed.hostname === 'aurelo.tech' || parsed.hostname.endsWith('.aurelo.tech')) {
+            return 'https://api.aurelo.tech/mcp/queue';
+        }
+    }
+    catch { }
+    return `${baseUrl.replace(/\/+$/, '')}/mcp/queue`;
+}
+function randomId() {
+    const cryptoRef = globalThis.crypto;
+    if (cryptoRef && typeof cryptoRef.randomUUID === 'function') {
+        return cryptoRef.randomUUID().replace(/-/g, '');
+    }
+    const parts = new Uint8Array(16);
+    if (cryptoRef && typeof cryptoRef.getRandomValues === 'function') {
+        cryptoRef.getRandomValues(parts);
+        return Array.from(parts, (part) => part.toString(16).padStart(2, '0')).join('');
+    }
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+}
+function normalizeClientId(value) {
+    const trimmed = String(value || '').trim();
+    const withoutPrefix = trimmed.startsWith('ext_') ? trimmed.slice(4) : trimmed;
+    return withoutPrefix.replace(/[^A-Za-z0-9_-]/g, '') || randomId();
+}
+function fullClientId(clientId) {
+    return clientId.startsWith('ext_') ? clientId : `ext_${clientId}`;
+}
+function createRequestId() {
+    return `req_${randomId()}`;
+}
+function createSession(clientId) {
+    const requestId = createRequestId();
+    return {
+        clientId,
+        requestId,
+        sessionId: `${fullClientId(clientId)}_${requestId}`,
+        createdAt: Date.now(),
+        status: 'active',
+    };
+}
+function reconnectCursorKey(sessionId) {
+    return `${RECONNECT_CURSOR_KEY_PREFIX}${sessionId}`;
+}
+export function createAureloClientId() {
+    return randomId();
+}
+export function normalizeAureloClientId(value) {
+    return normalizeClientId(value);
+}
+export function getAureloFullClientId(clientId) {
+    return fullClientId(normalizeClientId(clientId));
+}
+export function createAureloRequestId() {
+    return createRequestId();
+}
+export function createAureloSession(clientId) {
+    return createSession(normalizeClientId(clientId));
+}
+function readReason(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return '';
+    }
+    const value = payload;
+    const billing = value.billing && typeof value.billing === 'object'
+        ? value.billing
+        : null;
+    const rolloverReason = typeof billing?.rolloverReason === 'string' ? billing.rolloverReason : '';
+    if (rolloverReason === 'input') {
+        return 'input_threshold_reached';
+    }
+    if (rolloverReason === 'output') {
+        return 'output_threshold_reached';
+    }
+    return String(value.reason || value.code || '').trim();
+}
+function shouldRotate(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { rotate: false, reason: '' };
+    }
+    const value = payload;
+    const reason = readReason(payload);
+    const billing = value.billing && typeof value.billing === 'object'
+        ? value.billing
+        : null;
+    const rotate = value.rotateSession === true ||
+        ROTATION_REASONS.has(reason) ||
+        billing?.rolloverTriggered === true;
+    return { rotate, reason };
+}
+function parseSseCommentReason(comment) {
+    if (!comment.includes('aurelo-rotate-session')) {
+        return '';
+    }
+    const match = comment.match(/\breason=([^\s]+)/);
+    return match ? match[1] : 'request_closed';
+}
+function parseReconnectCursorComment(comment) {
+    if (!comment.includes('aurelo-reconnect-close')) {
+        return null;
+    }
+    const sessionMatch = comment.match(/\bsessionId=([^\s]+)/);
+    const cursorMatch = comment.match(/\bcursor=([0-9]+)/);
+    if (!sessionMatch || !cursorMatch) {
+        return null;
+    }
+    return {
+        sessionId: sessionMatch[1],
+        cursor: Number(cursorMatch[1]) || 0,
+    };
+}
+function isTerminalResponseType(type) {
+    return type === 'response.completed' || type === 'response.done';
+}
+function isAureloSdkError(value) {
+    return value instanceof AureloSDKError;
+}
+function getPayloadErrorMessage(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return '';
+    }
+    const value = payload;
+    return String(value.error || value.message || '').trim();
+}
+export class AureloSessionManager {
+    storage;
+    clientIdValue = null;
+    sessionValue = null;
+    constructor(options = {}) {
+        this.storage = options.storage || createDefaultStorage();
+        if (options.clientId) {
+            this.clientIdValue = normalizeClientId(options.clientId);
+        }
+    }
+    async getClientId() {
+        if (this.clientIdValue) {
+            return this.clientIdValue;
+        }
+        const stored = await this.storage.get(CLIENT_ID_KEY);
+        if (stored && stored.trim()) {
+            this.clientIdValue = normalizeClientId(stored);
+            return this.clientIdValue;
+        }
+        this.clientIdValue = randomId();
+        await this.storage.set(CLIENT_ID_KEY, this.clientIdValue);
+        return this.clientIdValue;
+    }
+    async getFullClientId() {
+        return fullClientId(await this.getClientId());
+    }
+    async getSession() {
+        if (this.sessionValue && this.sessionValue.status === 'active') {
+            return this.sessionValue;
+        }
+        const stored = await this.storage.get(SESSION_KEY);
+        if (stored) {
+            try {
+                const parsed = JSON.parse(stored);
+                if (parsed?.sessionId && parsed.status === 'active') {
+                    this.sessionValue = parsed;
+                    return parsed;
+                }
+            }
+            catch { }
+        }
+        return this.rotateSession('initial');
+    }
+    async getStoredActiveSession() {
+        if (this.sessionValue && this.sessionValue.status === 'active') {
+            return this.sessionValue;
+        }
+        const stored = await this.storage.get(SESSION_KEY);
+        if (!stored) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(stored);
+            if (parsed?.sessionId && parsed.status === 'active') {
+                this.sessionValue = parsed;
+                return parsed;
+            }
+        }
+        catch { }
+        return null;
+    }
+    async rotateSession(reason = 'manual') {
+        const clientId = await this.getClientId();
+        this.sessionValue = createSession(clientId);
+        this.sessionValue.rotationReason = reason;
+        await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+        return this.sessionValue;
+    }
+    async closeSession(reason = 'request_closed') {
+        const session = await this.getSession();
+        this.sessionValue = {
+            ...session,
+            status: 'closed',
+            rotationReason: reason,
+        };
+        await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+    }
+}
+export class AureloSDK {
+    apiKey;
+    baseUrl;
+    queueUrl;
+    fetchImpl;
+    storage;
+    clientIdValue = null;
+    sessionValue = null;
+    reconnectCursors = new Map();
+    constructor(options) {
+        if (!options.apiKey || !String(options.apiKey).trim()) {
+            throw new Error('AureloSDK requires apiKey.');
+        }
+        this.apiKey = String(options.apiKey).trim();
+        this.baseUrl = normalizeBaseUrl(options.baseUrl || 'https://aurelo.tech');
+        this.queueUrl = String(options.queueUrl || defaultQueueUrl(this.baseUrl)).trim();
+        this.fetchImpl = options.fetch || globalThis.fetch;
+        if (typeof this.fetchImpl !== 'function') {
+            throw new Error('AureloSDK requires fetch. Pass options.fetch in this runtime.');
+        }
+        this.storage = options.storage || createDefaultStorage();
+        if (options.clientId) {
+            this.clientIdValue = normalizeClientId(options.clientId);
+        }
+    }
+    async getClientId() {
+        if (this.clientIdValue) {
+            return this.clientIdValue;
+        }
+        const stored = await this.storage.get(CLIENT_ID_KEY);
+        if (stored && stored.trim()) {
+            this.clientIdValue = normalizeClientId(stored);
+            return this.clientIdValue;
+        }
+        this.clientIdValue = randomId();
+        await this.storage.set(CLIENT_ID_KEY, this.clientIdValue);
+        return this.clientIdValue;
+    }
+    async getFullClientId() {
+        return fullClientId(await this.getClientId());
+    }
+    async getSession() {
+        if (this.sessionValue && this.sessionValue.status === 'active') {
+            return this.sessionValue;
+        }
+        const stored = await this.storage.get(SESSION_KEY);
+        if (stored) {
+            try {
+                const parsed = JSON.parse(stored);
+                if (parsed?.sessionId && parsed.status === 'active') {
+                    this.sessionValue = parsed;
+                    return parsed;
+                }
+            }
+            catch { }
+        }
+        return this.rotateSession('initial');
+    }
+    async getStoredActiveSession() {
+        if (this.sessionValue && this.sessionValue.status === 'active') {
+            return this.sessionValue;
+        }
+        const stored = await this.storage.get(SESSION_KEY);
+        if (!stored) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(stored);
+            if (parsed?.sessionId && parsed.status === 'active') {
+                this.sessionValue = parsed;
+                return parsed;
+            }
+        }
+        catch { }
+        return null;
+    }
+    async rotateSession(reason = 'manual') {
+        const previousSessionId = this.sessionValue?.sessionId;
+        const clientId = await this.getClientId();
+        this.sessionValue = createSession(clientId);
+        this.sessionValue.rotationReason = reason;
+        if (previousSessionId) {
+            await this.clearReconnectCursor(previousSessionId);
+        }
+        await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+        return this.sessionValue;
+    }
+    async closeSession(reason = 'request_closed') {
+        const session = await this.getSession();
+        this.sessionValue = {
+            ...session,
+            status: 'closed',
+            rotationReason: reason,
+        };
+        await this.clearReconnectCursor(session.sessionId);
+        await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+    }
+    async markSessionClosed(session, reason = 'request_closed') {
+        this.sessionValue = {
+            ...session,
+            status: 'closed',
+            rotationReason: reason,
+        };
+        await this.clearReconnectCursor(session.sessionId);
+        await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+    }
+    async getReconnectCursor(sessionId) {
+        if (this.reconnectCursors.has(sessionId)) {
+            return this.reconnectCursors.get(sessionId) ?? null;
+        }
+        const stored = await this.storage.get(reconnectCursorKey(sessionId));
+        if (!stored) {
+            return null;
+        }
+        const cursor = Number(stored);
+        if (!Number.isFinite(cursor) || cursor < 0) {
+            return null;
+        }
+        this.reconnectCursors.set(sessionId, cursor);
+        return cursor;
+    }
+    async setReconnectCursor(sessionId, cursor) {
+        const normalizedCursor = Math.max(0, Math.floor(cursor));
+        this.reconnectCursors.set(sessionId, normalizedCursor);
+        await this.storage.set(reconnectCursorKey(sessionId), String(normalizedCursor));
+    }
+    async clearReconnectCursor(sessionId) {
+        this.reconnectCursors.delete(sessionId);
+        if (this.storage.delete) {
+            await this.storage.delete(reconnectCursorKey(sessionId));
+        }
+        else {
+            await this.storage.set(reconnectCursorKey(sessionId), '');
+        }
+    }
+    async observeSseComment(comment) {
+        const normalizedComment = String(comment || '').trim();
+        if (!normalizedComment) {
+            return;
+        }
+        const reconnectCursor = parseReconnectCursorComment(normalizedComment);
+        if (reconnectCursor) {
+            await this.setReconnectCursor(reconnectCursor.sessionId, reconnectCursor.cursor);
+        }
+        const reason = parseSseCommentReason(normalizedComment);
+        if (reason) {
+            await this.rotateSession(reason);
+        }
+    }
+    async queueMessage(request) {
+        const session = await this.getSession();
+        const queueRequest = typeof request === 'string'
+            ? { message: request }
+            : request;
+        const message = String(queueRequest.message || '').trim();
+        if (!message) {
+            throw new Error('AureloSDK queueMessage requires message.');
+        }
+        const sessionId = String(queueRequest.sessionId || session.sessionId).trim();
+        const metadata = {
+            ...(queueRequest.metadata || {}),
+            clientId: fullClientId(session.clientId),
+            requestId: session.requestId,
+            sessionId,
+        };
+        const response = await this.fetchImpl(this.queueUrl, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                sessionId,
+                message,
+                source: queueRequest.source || 'aurelo-sdk',
+                requestId: queueRequest.requestId || session.requestId,
+                publicModel: queueRequest.publicModel || queueRequest.model,
+                metadata,
+            }),
+            signal: queueRequest.signal,
+        });
+        if (!response.ok) {
+            const payload = await this.readErrorPayload(response);
+            const rotation = shouldRotate(payload);
+            if (rotation.rotate) {
+                await this.rotateSession(rotation.reason || 'backend_rotation');
+            }
+            throw new AureloSDKError(`Aurelo queue failed with HTTP ${response.status}`, {
+                status: response.status,
+                reason: rotation.reason,
+                rotateSession: rotation.rotate,
+                payload,
+            });
+        }
+        return this.readResponsePayload(response);
+    }
+    async createResponse(request, options = {}) {
+        const session = await this.getSession();
+        const metadata = {
+            ...(request.metadata || {}),
+            clientId: fullClientId(session.clientId),
+            requestId: session.requestId,
+            sessionId: session.sessionId,
+        };
+        const body = {
+            ...request,
+            metadata,
+        };
+        const response = await this.fetchImpl(`${this.baseUrl}/v1/responses`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: options.signal,
+        });
+        if (!response.ok) {
+            const payload = await this.readErrorPayload(response);
+            const rotation = shouldRotate(payload);
+            const reason = rotation.reason || `http_${response.status}`;
+            const payloadMessage = getPayloadErrorMessage(payload);
+            await this.markSessionClosed(session, reason);
+            throw new AureloSDKError(`Aurelo request failed with HTTP ${response.status}${rotation.reason ? ` (${rotation.reason})` : ''}${payloadMessage ? `: ${payloadMessage}` : ''}`, {
+                status: response.status,
+                reason: rotation.reason,
+                rotateSession: rotation.rotate,
+                payload,
+            });
+        }
+        const responseSessionId = response.headers.get('x-aurelo-session-id');
+        if (responseSessionId && responseSessionId !== session.sessionId) {
+            this.sessionValue = {
+                ...session,
+                sessionId: responseSessionId,
+            };
+            await this.storage.set(SESSION_KEY, JSON.stringify(this.sessionValue));
+        }
+        return response;
+    }
+    async createResponseWithRotationRetry(request, options = {}) {
+        try {
+            return await this.createResponse(request, options);
+        }
+        catch (error) {
+            if (isAureloSdkError(error) && error.rotateSession) {
+                return this.createResponse(request, options);
+            }
+            throw error;
+        }
+    }
+    async createOrContinueResponse(request, options = {}) {
+        const message = typeof request.input === 'string' ? request.input.trim() : '';
+        const existingSession = await this.getStoredActiveSession();
+        if (!existingSession || !message) {
+            return this.createResponseWithRotationRetry(request, options);
+        }
+        const existingCursor = await this.getReconnectCursor(existingSession.sessionId);
+        if (existingCursor === null) {
+            await this.markSessionClosed(existingSession, 'missing_reconnect_cursor');
+            return this.createResponseWithRotationRetry(request, options);
+        }
+        try {
+            await this.queueMessage({
+                message,
+                model: request.model,
+                publicModel: request.model,
+                metadata: request.metadata,
+                signal: options.signal,
+            });
+            return this.reconnect({
+                model: request.model,
+                input: request.input,
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (isAureloSdkError(error) && error.rotateSession) {
+                return this.createResponseWithRotationRetry(request, options);
+            }
+            throw error;
+        }
+    }
+    async *streamResponse(request, options = {}) {
+        const response = await this.createResponseWithRotationRetry({ ...request, stream: true }, options);
+        yield* this.streamEventsFromResponse(response);
+    }
+    async *streamReconnect(request = {}) {
+        const response = await this.reconnect(request);
+        yield* this.streamEventsFromResponse(response);
+    }
+    async *continueResponse(message, request = {}) {
+        const model = request.model || request.publicModel || 'M1';
+        try {
+            await this.queueMessage({
+                ...request,
+                message,
+            });
+            yield* this.streamReconnect({
+                ...request,
+                model,
+                input: message,
+            });
+        }
+        catch (error) {
+            if (isAureloSdkError(error) && error.rotateSession) {
+                const response = await this.createResponseWithRotationRetry({
+                    model,
+                    input: message,
+                    stream: true,
+                    metadata: request.metadata,
+                }, { signal: request.signal });
+                yield* this.streamEventsFromResponse(response);
+                return;
+            }
+            throw error;
+        }
+    }
+    async *streamEventsFromResponse(response) {
+        if (!response.body) {
+            yield { type: 'done', raw: '' };
+            await this.closeSession('request_closed');
+            return;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || '';
+                for (const line of lines) {
+                    const event = await this.handleSseLine(line);
+                    if (event) {
+                        yield event;
+                    }
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.trim()) {
+                const event = await this.handleSseLine(buffer);
+                if (event) {
+                    yield event;
+                }
+            }
+            yield { type: 'done', raw: '' };
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    async reconnect(request = {}) {
+        const session = request.sessionId
+            ? { ...(await this.getSession()), sessionId: request.sessionId }
+            : await this.getSession();
+        const storedCursor = await this.getReconnectCursor(session.sessionId);
+        const cursor = request.cursor ?? storedCursor ?? 0;
+        const metadata = {
+            clientId: fullClientId(session.clientId),
+            requestId: session.requestId,
+            sessionId: session.sessionId,
+        };
+        const body = {
+            model: request.model || 'M1',
+            input: request.input || '',
+            stream: true,
+            metadata: {
+                ...metadata,
+                aureloAction: 'reconnect',
+                cursor,
+            },
+        };
+        const response = await this.fetchImpl(`${this.baseUrl}/v1/responses`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: request.signal,
+        });
+        if (!response.ok) {
+            const payload = await this.readErrorPayload(response);
+            const rotation = shouldRotate(payload);
+            if (rotation.rotate) {
+                await this.rotateSession(rotation.reason || 'backend_rotation');
+            }
+            if (rotation.rotate && String(payload?.nextAction || '') === 'start_new_request') {
+                return this.createResponse({
+                    model: body.model,
+                    input: body.input,
+                    stream: true,
+                }, { signal: request.signal });
+            }
+            throw new AureloSDKError(`Aurelo reconnect failed with HTTP ${response.status}`, {
+                status: response.status,
+                reason: rotation.reason,
+                rotateSession: rotation.rotate,
+                payload,
+            });
+        }
+        return response;
+    }
+    async handleSseLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (trimmed.startsWith(':')) {
+            const comment = trimmed.slice(1).trim();
+            await this.observeSseComment(comment);
+            return { type: 'comment', raw: line, comment };
+        }
+        if (trimmed === 'data: [DONE]') {
+            await this.closeSession('request_closed');
+            return { type: 'done', raw: line };
+        }
+        if (!trimmed.startsWith('data: ')) {
+            return { type: 'event', raw: line, data: trimmed };
+        }
+        let data = trimmed.slice(6);
+        try {
+            data = JSON.parse(trimmed.slice(6));
+        }
+        catch { }
+        const eventType = data && typeof data === 'object'
+            ? String(data.type || '')
+            : '';
+        const rotation = shouldRotate(data);
+        if (rotation.rotate) {
+            await this.rotateSession(rotation.reason || 'backend_rotation');
+        }
+        else if (isTerminalResponseType(eventType)) {
+            await this.closeSession(eventType === 'response.done' ? 'response_done' : 'response_completed');
+        }
+        return { type: 'event', raw: line, data };
+    }
+    async readErrorPayload(response) {
+        const text = await response.text();
+        if (!text) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { error: text };
+        }
+    }
+    async readResponsePayload(response) {
+        const text = await response.text();
+        if (!text) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+}
+export default AureloSDK;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@aurelo_npm/sdk",
+  "version": "0.1.0",
+  "description": "Aurelo API-key SDK with stable client identity and backend-driven session rotation.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.2"
+  }
+}