@hyperyai/sdk 1.0.0

package/dist/lib/parse-error.js

@@ -0,0 +1,185 @@
+const SPENDING_LIMIT = 'SPENDING_LIMIT_EXCEEDED';
+const INSUFFICIENT_CREDITS = 'INSUFFICIENT_CREDITS';
+const PAYMENT_METHOD_REQUIRED = 'PAYMENT_METHOD_REQUIRED';
+const PAYMENT_DECLINED = 'PAYMENT_DECLINED';
+const UNAUTHENTICATED = 'UNAUTHENTICATED';
+const PERMISSION_DENIED = 'PERMISSION_DENIED';
+const INSUFFICIENT_SCOPE = 'INSUFFICIENT_SCOPE';
+const RATE_LIMITED = 'RATE_LIMITED';
+/**
+ * Extract the inner error object from any of the shapes the gateway / a caller
+ * may hand us:
+ *   - the raw server envelope: `{ error: { code, message, type, ... } }`
+ *   - an already-unwrapped error object: `{ code, message, type, ... }`
+ * Returns undefined if neither shape carries a `code`.
+ */
+function unwrap(error) {
+    if (error && typeof error === 'object') {
+        if (error.error && typeof error.error === 'object' && 'code' in error.error) {
+            return error.error;
+        }
+        if (typeof error.code === 'string') {
+            return error;
+        }
+    }
+    return undefined;
+}
+/** Pull an HTTP status off a Response-like / thrown-error object, if present. */
+function statusOf(error) {
+    const s = error?.status ?? error?.statusCode ?? error?.response?.status;
+    return typeof s === 'number' ? s : undefined;
+}
+/**
+ * Parse an error (a parsed JSON body, a thrown error, or a Response-like object)
+ * from the Hypery API into a normalized, classified shape. Tolerant of both the
+ * `{ error: { code } }` envelope and an already-unwrapped object, and falls back
+ * to the HTTP status when no recognized `code` is present.
+ */
+export function parseError(error) {
+    const errorData = unwrap(error);
+    const status = statusOf(error);
+    if (errorData) {
+        const code = errorData.code;
+        return {
+            code,
+            message: errorData.message,
+            type: errorData.type,
+            status,
+            isSpendingLimit: code === SPENDING_LIMIT,
+            isInsufficientCredits: code === INSUFFICIENT_CREDITS,
+            isPaymentMethodRequired: code === PAYMENT_METHOD_REQUIRED,
+            isPaymentDeclined: code === PAYMENT_DECLINED,
+            isAuth: code === UNAUTHENTICATED || errorData.type === 'authentication_error',
+            isPermissionDenied: code === PERMISSION_DENIED ||
+                code === INSUFFICIENT_SCOPE ||
+                errorData.type === 'permission_error' ||
+                errorData.type === 'authorization_error',
+            isRateLimit: code === RATE_LIMITED || errorData.type === 'rate_limit_error',
+            data: errorData,
+        };
+    }
+    // No recognized code — classify from HTTP status so a payment/auth modal can
+    // still open for an endpoint that returns a non-canonical body.
+    if (status === 402) {
+        return statusFallback(INSUFFICIENT_CREDITS, 'Insufficient credits.', status, {
+            isInsufficientCredits: true,
+        });
+    }
+    if (status === 401) {
+        return statusFallback(UNAUTHENTICATED, 'Authentication required.', status, { isAuth: true });
+    }
+    if (status === 403) {
+        return statusFallback(PERMISSION_DENIED, 'You do not have permission to perform this action.', status, {
+            isPermissionDenied: true,
+        });
+    }
+    if (status === 429) {
+        return statusFallback(RATE_LIMITED, 'Rate limit exceeded. Please retry shortly.', status, {
+            isRateLimit: true,
+        });
+    }
+    // Handle generic errors
+    const message = error?.message || 'An unknown error occurred';
+    return {
+        code: 'UNKNOWN_ERROR',
+        message,
+        status,
+        isSpendingLimit: false,
+        isInsufficientCredits: false,
+        isPaymentMethodRequired: false,
+        isPaymentDeclined: false,
+        isAuth: false,
+        isPermissionDenied: false,
+        isRateLimit: false,
+        data: {
+            code: 'UNKNOWN_ERROR',
+            message,
+        },
+    };
+}
+function statusFallback(code, message, status, flags) {
+    return {
+        code,
+        message,
+        status,
+        isSpendingLimit: false,
+        isInsufficientCredits: false,
+        isPaymentMethodRequired: false,
+        isPaymentDeclined: false,
+        isAuth: false,
+        isPermissionDenied: false,
+        isRateLimit: false,
+        ...flags,
+        data: { code, message },
+    };
+}
+/**
+ * Check if an error is a spending limit error
+ */
+export function isSpendingLimitError(error) {
+    return parseError(error).isSpendingLimit;
+}
+/**
+ * Check if an error is an insufficient credits error
+ */
+export function isInsufficientCreditsError(error) {
+    return parseError(error).isInsufficientCredits;
+}
+/**
+ * Check if an error means the user must add a payment method (metered billing).
+ */
+export function isPaymentMethodRequiredError(error) {
+    return parseError(error).isPaymentMethodRequired;
+}
+/**
+ * Check if an error means the user's card was declined (metered billing).
+ */
+export function isPaymentDeclinedError(error) {
+    return parseError(error).isPaymentDeclined;
+}
+/**
+ * Check if an error is an authentication failure (re-auth / open the auth modal).
+ */
+export function isAuthError(error) {
+    return parseError(error).isAuth;
+}
+/**
+ * Check if an error is a scope/permission denial (403) — NOT an auth failure,
+ * so it should not trigger re-auth.
+ */
+export function isPermissionDeniedError(error) {
+    return parseError(error).isPermissionDenied;
+}
+/**
+ * Check if an error is a rate-limit denial (429 / RATE_LIMITED).
+ */
+export function isRateLimitError(error) {
+    return parseError(error).isRateLimit;
+}
+/**
+ * Any billing restriction the funds widget should surface a CTA for.
+ */
+export function isBillingRestriction(error) {
+    return (isSpendingLimitError(error) ||
+        isInsufficientCreditsError(error) ||
+        isPaymentMethodRequiredError(error) ||
+        isPaymentDeclinedError(error));
+}
+/**
+ * Format time until reset
+ */
+export function formatTimeUntilReset(resetsAt) {
+    if (!resetsAt)
+        return '';
+    const reset = new Date(resetsAt);
+    const now = new Date();
+    const diff = reset.getTime() - now.getTime();
+    if (diff < 0)
+        return 'soon';
+    const hours = Math.floor(diff / (1000 * 60 * 60));
+    const minutes = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60));
+    if (hours > 0) {
+        return `in ${hours}h ${minutes}m`;
+    }
+    return `in ${minutes}m`;
+}

package/dist/lib/parse-stream.d.ts

@@ -0,0 +1,43 @@
+import type { ParsedError } from "../types";
+/**
+ * Streaming (SSE) error classification for the gateway's chat/completions stream.
+ *
+ * A pre-stream denial arrives as a normal HTTP 402/429/403 with a JSON body —
+ * `parseError` already handles that. But a failure AFTER the stream has started
+ * (e.g. a billing/finalize error) is delivered as an SSE `event: error` frame,
+ * which a fetch-stream consumer must parse itself. These helpers surface that
+ * terminal error in the EXACT same classified shape as a non-streaming error,
+ * because the gateway now emits the canonical `{ error: { code, type, message } }`
+ * envelope inside the frame's `data:` (see lib/errors/api-error.ts).
+ */
+export interface SSEEvent {
+    /** The `event:` name, if the frame set one (e.g. `error`). */
+    event?: string;
+    /** The concatenated `data:` payload. */
+    data: string;
+}
+/** Parse a raw SSE frame block (the text between blank-line delimiters). */
+export declare function parseSSEFrame(block: string): SSEEvent | null;
+/**
+ * If a frame is a terminal error — either `event: error`, or a `data:` payload
+ * carrying the canonical `{ error: { code } }` envelope — return the classified
+ * ParsedError (identical to `parseError()` for a non-streaming failure).
+ * Returns null for a normal data frame or the `[DONE]` sentinel.
+ */
+export declare function parseSSEError(frame: SSEEvent | string): ParsedError | null;
+export interface SSEStreamHandlers {
+    /** Called with each normal SSE `data:` payload (e.g. an OpenAI delta chunk). */
+    onData?: (data: string) => void;
+    /** Called ONCE with a classified error if the stream ends in an error frame. */
+    onError?: (error: ParsedError) => void;
+    /** Called when the stream completes (after `[DONE]` or the body closing). */
+    onDone?: () => void;
+}
+/**
+ * Consume a streaming Response body (`fetch(...).body`), splitting it into SSE
+ * frames. Normal data frames go to `onData`; a terminal `event: error` frame is
+ * classified and delivered to `onError` (NOT thrown), so a consumer using raw
+ * fetch-stream parsing gets the same `ParsedError` it would from a non-streaming
+ * call and can drive the same billing/auth modal. Resolves when the stream ends.
+ */
+export declare function consumeSSEStream(body: ReadableStream<Uint8Array> | null | undefined, handlers: SSEStreamHandlers): Promise<void>;

package/dist/lib/parse-stream.js

@@ -0,0 +1,89 @@
+import { parseError } from "./parse-error";
+/** Parse a raw SSE frame block (the text between blank-line delimiters). */
+export function parseSSEFrame(block) {
+    let event;
+    const dataLines = [];
+    for (const line of block.split("\n")) {
+        if (line.startsWith("event:")) {
+            event = line.slice(6).trim();
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+        }
+    }
+    if (!event && dataLines.length === 0)
+        return null;
+    return { event, data: dataLines.join("\n") };
+}
+/**
+ * If a frame is a terminal error — either `event: error`, or a `data:` payload
+ * carrying the canonical `{ error: { code } }` envelope — return the classified
+ * ParsedError (identical to `parseError()` for a non-streaming failure).
+ * Returns null for a normal data frame or the `[DONE]` sentinel.
+ */
+export function parseSSEError(frame) {
+    const f = typeof frame === "string" ? parseSSEFrame(frame) : frame;
+    if (!f)
+        return null;
+    if (f.data === "[DONE]")
+        return null;
+    const isErrorEvent = f.event === "error";
+    let payload;
+    try {
+        payload = JSON.parse(f.data);
+    }
+    catch {
+        // Non-JSON data on an error frame — still surface it as a classified error.
+        return isErrorEvent ? parseError({ message: f.data }) : null;
+    }
+    const hasEnvelope = !!payload &&
+        typeof payload === "object" &&
+        typeof payload.error === "object" &&
+        payload.error !== null &&
+        "code" in payload.error;
+    return isErrorEvent || hasEnvelope ? parseError(payload) : null;
+}
+/**
+ * Consume a streaming Response body (`fetch(...).body`), splitting it into SSE
+ * frames. Normal data frames go to `onData`; a terminal `event: error` frame is
+ * classified and delivered to `onError` (NOT thrown), so a consumer using raw
+ * fetch-stream parsing gets the same `ParsedError` it would from a non-streaming
+ * call and can drive the same billing/auth modal. Resolves when the stream ends.
+ */
+export async function consumeSSEStream(body, handlers) {
+    if (!body) {
+        handlers.onDone?.();
+        return;
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buffer.indexOf("\n\n")) !== -1) {
+                const block = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                const frame = parseSSEFrame(block);
+                if (!frame)
+                    continue;
+                const err = parseSSEError(frame);
+                if (err) {
+                    handlers.onError?.(err);
+                    continue;
+                }
+                if (frame.data === "[DONE]")
+                    continue;
+                handlers.onData?.(frame.data);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    handlers.onDone?.();
+}

package/dist/lib/popup.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Popup helpers for the seamless (in-page) auth + charge flow.
+ *
+ * Both auth and Stripe card-entry can run in a popup so the whole
+ * press-buy → login → add-card → charge chain completes without leaving the
+ * developer's page (the PayPal / Firebase `signInWithPopup` model). Each helper
+ * resolves when the popup posts a completion message from the expected origin,
+ * or when the popup closes (treated as a cancel). If the browser blocks the
+ * popup, the helper returns `'blocked'` so the caller can fall back to redirect.
+ */
+import type { InteractionMode, ResolvedMode } from '../types';
+/**
+ * Resolve the effective mode. `auto` prefers popup on desktop but falls back to
+ * redirect on mobile / in-app webviews, where popups are unreliable (this mirrors
+ * Firebase's "popup on web, redirect on mobile" guidance).
+ */
+export declare function resolveInteractionMode(mode: InteractionMode | undefined): ResolvedMode;
+interface PopupOptions {
+    url: string;
+    /** window.open target name; also read back in the callback to detect popup context. */
+    name: string;
+    /** Only completion messages from this origin are trusted. */
+    expectedOrigin: string;
+    /** Message discriminator to accept (e.g. 'hypery:auth', 'hypery:payment-method'). */
+    messageType: string;
+    width?: number;
+    height?: number;
+}
+export type PopupResult<T> = {
+    blocked: true;
+} | {
+    blocked: false;
+    cancelled: boolean;
+    data?: T;
+};
+/**
+ * Open `url` in a popup and resolve when it posts `{ type: messageType, ... }`
+ * from `expectedOrigin`, or when it closes (cancelled). Returns `{ blocked: true }`
+ * if the browser blocked the popup.
+ */
+export declare function openPopup<T = any>(opts: PopupOptions): Promise<PopupResult<T>>;
+export {};

package/dist/lib/popup.js

@@ -0,0 +1,80 @@
+/**
+ * Popup helpers for the seamless (in-page) auth + charge flow.
+ *
+ * Both auth and Stripe card-entry can run in a popup so the whole
+ * press-buy → login → add-card → charge chain completes without leaving the
+ * developer's page (the PayPal / Firebase `signInWithPopup` model). Each helper
+ * resolves when the popup posts a completion message from the expected origin,
+ * or when the popup closes (treated as a cancel). If the browser blocks the
+ * popup, the helper returns `'blocked'` so the caller can fall back to redirect.
+ */
+/**
+ * Resolve the effective mode. `auto` prefers popup on desktop but falls back to
+ * redirect on mobile / in-app webviews, where popups are unreliable (this mirrors
+ * Firebase's "popup on web, redirect on mobile" guidance).
+ */
+export function resolveInteractionMode(mode) {
+    const m = mode || 'auto';
+    if (m === 'popup' || m === 'redirect')
+        return m;
+    if (typeof navigator === 'undefined')
+        return 'redirect';
+    const ua = navigator.userAgent || '';
+    const isMobile = /Android|iPhone|iPad|iPod|Mobile|Silk|Kindle|BlackBerry|Opera Mini/i.test(ua);
+    return isMobile ? 'redirect' : 'popup';
+}
+function centeredFeatures(w, h) {
+    // Best-effort centering; harmless if the values are unavailable (SSR-guarded caller).
+    const dualLeft = typeof window !== 'undefined' ? (window.screenLeft ?? 0) : 0;
+    const dualTop = typeof window !== 'undefined' ? (window.screenTop ?? 0) : 0;
+    const width = typeof window !== 'undefined' ? window.innerWidth || w : w;
+    const height = typeof window !== 'undefined' ? window.innerHeight || h : h;
+    const left = dualLeft + Math.max(0, (width - w) / 2);
+    const top = dualTop + Math.max(0, (height - h) / 2);
+    return `width=${w},height=${h},left=${Math.round(left)},top=${Math.round(top)},resizable=yes,scrollbars=yes`;
+}
+/**
+ * Open `url` in a popup and resolve when it posts `{ type: messageType, ... }`
+ * from `expectedOrigin`, or when it closes (cancelled). Returns `{ blocked: true }`
+ * if the browser blocked the popup.
+ */
+export function openPopup(opts) {
+    if (typeof window === 'undefined') {
+        return Promise.resolve({ blocked: false, cancelled: true });
+    }
+    const popup = window.open(opts.url, opts.name, centeredFeatures(opts.width || 480, opts.height || 720));
+    if (!popup) {
+        return Promise.resolve({ blocked: true });
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener('message', onMessage);
+            clearInterval(poll);
+            resolve(result);
+        };
+        const onMessage = (event) => {
+            if (event.origin !== opts.expectedOrigin)
+                return;
+            const data = event.data;
+            if (data && typeof data === 'object' && data.type === opts.messageType) {
+                try {
+                    popup.close();
+                }
+                catch {
+                    /* cross-origin close may throw; ignore */
+                }
+                finish({ blocked: false, cancelled: false, data: data });
+            }
+        };
+        window.addEventListener('message', onMessage);
+        // Fallback: if the popup is closed without a message, treat it as a cancel.
+        const poll = setInterval(() => {
+            if (popup.closed)
+                finish({ blocked: false, cancelled: true });
+        }, 500);
+    });
+}

package/dist/lib/storage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Token storage utilities
+ */
+import type { AuthTokens, User } from '../types';
+export declare class TokenStorage {
+    private storage;
+    private storageType;
+    constructor(storageType?: 'localStorage' | 'sessionStorage' | 'memory');
+    /**
+     * Save auth tokens
+     */
+    saveTokens(tokens: AuthTokens): void;
+    /**
+     * Get auth tokens
+     */
+    getTokens(): (AuthTokens & {
+        savedAt: number;
+    }) | null;
+    /**
+     * Check if access token is expired
+     */
+    isTokenExpired(): boolean;
+    /**
+     * Clear auth tokens
+     */
+    clearTokens(): void;
+    /**
+     * Save user info
+     */
+    saveUser(user: User): void;
+    /**
+     * Get user info
+     */
+    getUser(): User | null;
+    /**
+     * Clear user info
+     */
+    clearUser(): void;
+    /**
+     * Clear all auth data
+     */
+    clear(): void;
+}

package/dist/lib/storage.js

@@ -0,0 +1,125 @@
+/**
+ * Token storage utilities
+ */
+const TOKEN_KEY = 'hypery_auth_tokens';
+const USER_KEY = 'hypery_auth_user';
+export class TokenStorage {
+    constructor(storageType = 'localStorage') {
+        this.storageType = storageType;
+        if (storageType === 'memory' || typeof window === 'undefined') {
+            // In-memory storage for SSR or memory mode
+            this.storage = new Map();
+        }
+        else {
+            this.storage = storageType === 'localStorage' ? localStorage : sessionStorage;
+        }
+    }
+    /**
+     * Save auth tokens
+     */
+    saveTokens(tokens) {
+        const data = JSON.stringify({
+            ...tokens,
+            savedAt: Date.now(),
+        });
+        if (this.storage instanceof Map) {
+            this.storage.set(TOKEN_KEY, data);
+        }
+        else {
+            this.storage.setItem(TOKEN_KEY, data);
+        }
+    }
+    /**
+     * Get auth tokens
+     */
+    getTokens() {
+        let data = null;
+        if (this.storage instanceof Map) {
+            data = this.storage.get(TOKEN_KEY) || null;
+        }
+        else {
+            data = this.storage.getItem(TOKEN_KEY);
+        }
+        if (!data)
+            return null;
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if access token is expired
+     */
+    isTokenExpired() {
+        const tokens = this.getTokens();
+        if (!tokens)
+            return true;
+        const expiresAt = tokens.savedAt + tokens.expiresIn * 1000;
+        const now = Date.now();
+        // Add 60s buffer to refresh before expiration
+        return now >= expiresAt - 60000;
+    }
+    /**
+     * Clear auth tokens
+     */
+    clearTokens() {
+        if (this.storage instanceof Map) {
+            this.storage.delete(TOKEN_KEY);
+        }
+        else {
+            this.storage.removeItem(TOKEN_KEY);
+        }
+    }
+    /**
+     * Save user info
+     */
+    saveUser(user) {
+        const data = JSON.stringify(user);
+        if (this.storage instanceof Map) {
+            this.storage.set(USER_KEY, data);
+        }
+        else {
+            this.storage.setItem(USER_KEY, data);
+        }
+    }
+    /**
+     * Get user info
+     */
+    getUser() {
+        let data = null;
+        if (this.storage instanceof Map) {
+            data = this.storage.get(USER_KEY) || null;
+        }
+        else {
+            data = this.storage.getItem(USER_KEY);
+        }
+        if (!data)
+            return null;
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clear user info
+     */
+    clearUser() {
+        if (this.storage instanceof Map) {
+            this.storage.delete(USER_KEY);
+        }
+        else {
+            this.storage.removeItem(USER_KEY);
+        }
+    }
+    /**
+     * Clear all auth data
+     */
+    clear() {
+        this.clearTokens();
+        this.clearUser();
+    }
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for @hyperyai/sdk
+ */
+import { type ClassValue } from "clsx";
+/**
+ * Merge Tailwind CSS classes with proper precedence
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/utils.js

@@ -0,0 +1,11 @@
+/**
+ * Utility functions for @hyperyai/sdk
+ */
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+/**
+ * Merge Tailwind CSS classes with proper precedence
+ */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}