@hyperyai/sdk 1.0.0

package/src/lib/parse-error.ts

@@ -0,0 +1,224 @@
+import { ErrorData, ParsedError } from '../types';
+
+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: any): ErrorData | undefined {
+  if (error && typeof error === 'object') {
+    if (error.error && typeof error.error === 'object' && 'code' in error.error) {
+      return error.error as ErrorData;
+    }
+    if (typeof error.code === 'string') {
+      return error as ErrorData;
+    }
+  }
+  return undefined;
+}
+
+/** Pull an HTTP status off a Response-like / thrown-error object, if present. */
+function statusOf(error: any): number | undefined {
+  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: any): ParsedError {
+  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: string,
+  message: string,
+  status: number,
+  flags: Partial<
+    Pick<
+      ParsedError,
+      | 'isSpendingLimit'
+      | 'isInsufficientCredits'
+      | 'isPaymentMethodRequired'
+      | 'isPaymentDeclined'
+      | 'isAuth'
+      | 'isPermissionDenied'
+      | 'isRateLimit'
+    >
+  >,
+): ParsedError {
+  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: any): boolean {
+  return parseError(error).isSpendingLimit;
+}
+
+/**
+ * Check if an error is an insufficient credits error
+ */
+export function isInsufficientCreditsError(error: any): boolean {
+  return parseError(error).isInsufficientCredits;
+}
+
+/**
+ * Check if an error means the user must add a payment method (metered billing).
+ */
+export function isPaymentMethodRequiredError(error: any): boolean {
+  return parseError(error).isPaymentMethodRequired;
+}
+
+/**
+ * Check if an error means the user's card was declined (metered billing).
+ */
+export function isPaymentDeclinedError(error: any): boolean {
+  return parseError(error).isPaymentDeclined;
+}
+
+/**
+ * Check if an error is an authentication failure (re-auth / open the auth modal).
+ */
+export function isAuthError(error: any): boolean {
+  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: any): boolean {
+  return parseError(error).isPermissionDenied;
+}
+
+/**
+ * Check if an error is a rate-limit denial (429 / RATE_LIMITED).
+ */
+export function isRateLimitError(error: any): boolean {
+  return parseError(error).isRateLimit;
+}
+
+/**
+ * Any billing restriction the funds widget should surface a CTA for.
+ */
+export function isBillingRestriction(error: any): boolean {
+  return (
+    isSpendingLimitError(error) ||
+    isInsufficientCreditsError(error) ||
+    isPaymentMethodRequiredError(error) ||
+    isPaymentDeclinedError(error)
+  );
+}
+
+/**
+ * Format time until reset
+ */
+export function formatTimeUntilReset(resetsAt?: string): string {
+  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/src/lib/parse-stream.ts

@@ -0,0 +1,121 @@
+import type { ParsedError } from "../types";
+import { parseError } from "./parse-error";
+
+/**
+ * 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 function parseSSEFrame(block: string): SSEEvent | null {
+  let event: string | undefined;
+  const dataLines: string[] = [];
+  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: SSEEvent | string): ParsedError | null {
+  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: unknown;
+  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 as any).error === "object" &&
+    (payload as any).error !== null &&
+    "code" in (payload as any).error;
+
+  return isErrorEvent || hasEnvelope ? parseError(payload) : 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 async function consumeSSEStream(
+  body: ReadableStream<Uint8Array> | null | undefined,
+  handlers: SSEStreamHandlers,
+): Promise<void> {
+  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: number;
+      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/src/lib/popup.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 function resolveInteractionMode(mode: InteractionMode | undefined): ResolvedMode {
+  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: number, h: number): string {
+  // 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`;
+}
+
+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 function openPopup<T = any>(opts: PopupOptions): Promise<PopupResult<T>> {
+  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<PopupResult<T>>((resolve) => {
+    let settled = false;
+    const finish = (result: PopupResult<T>) => {
+      if (settled) return;
+      settled = true;
+      window.removeEventListener('message', onMessage);
+      clearInterval(poll);
+      resolve(result);
+    };
+    const onMessage = (event: MessageEvent) => {
+      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 as T });
+      }
+    };
+    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/src/lib/storage.ts

@@ -0,0 +1,140 @@
+/**
+ * Token storage utilities
+ */
+
+import type { AuthTokens, User } from '../types';
+
+const TOKEN_KEY = 'hypery_auth_tokens';
+const USER_KEY = 'hypery_auth_user';
+
+export class TokenStorage {
+  private storage: Storage | Map<string, string>;
+  private storageType: 'localStorage' | 'sessionStorage' | 'memory';
+
+  constructor(storageType: 'localStorage' | 'sessionStorage' | 'memory' = 'localStorage') {
+    this.storageType = storageType;
+
+    if (storageType === 'memory' || typeof window === 'undefined') {
+      // In-memory storage for SSR or memory mode
+      this.storage = new Map<string, string>();
+    } else {
+      this.storage = storageType === 'localStorage' ? localStorage : sessionStorage;
+    }
+  }
+
+  /**
+   * Save auth tokens
+   */
+  saveTokens(tokens: AuthTokens): void {
+    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(): (AuthTokens & { savedAt: number }) | null {
+    let data: string | null = 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(): boolean {
+    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(): void {
+    if (this.storage instanceof Map) {
+      this.storage.delete(TOKEN_KEY);
+    } else {
+      this.storage.removeItem(TOKEN_KEY);
+    }
+  }
+
+  /**
+   * Save user info
+   */
+  saveUser(user: User): void {
+    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(): User | null {
+    let data: string | null = 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(): void {
+    if (this.storage instanceof Map) {
+      this.storage.delete(USER_KEY);
+    } else {
+      this.storage.removeItem(USER_KEY);
+    }
+  }
+
+  /**
+   * Clear all auth data
+   */
+  clear(): void {
+    this.clearTokens();
+    this.clearUser();
+  }
+}
+

package/src/lib/utils.ts

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