magically-sdk/types.ts

Official SDK for Magically - Build mobile apps with AI

// Core Types for Magically SDK

export interface User {
  _id: string;
  id: string;
  email: string;
  name: string;
  firstName?: string;
  lastName?: string;
}

export interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;
  token?: string | null; // JWT token stored in memory for edge environments
}

export interface TokenData {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  tokenType: string;
}

export interface DataQueryOptions {
  sort?: Record<string, 1 | -1>;
  limit?: number;
  skip?: number;
}

export interface DataQueryResult<T> {
  data: T[];
  total: number;
}

export interface DataInsertOptions<T = any> {
  data: T;
  upsert?: boolean; // If true, update if exists, insert if not
}

// Standard fields that are automatically added to all documents
export interface StandardFields {
  _id: string; // MongoDB ObjectId as string
  creator: string; // MongoDB ObjectId as string
  createdAt: Date;
  updatedAt: Date;
  isPublic?: boolean; // Optional: true = visible to all users, false/undefined = private to creator
}

// LLM API Types
export interface LLMTextContent {
  type: 'text';
  text: string;
}

export interface LLMImageContent {
  type: 'image';
  image: string | URL; // Can be base64 string or URL
}

export type LLMContent = LLMTextContent | LLMImageContent;

export interface LLMMessage {
  role: 'system' | 'user' | 'assistant';
  content: string | LLMContent[];
}

export interface InvokeOptions {
  model?: string;
  temperature?: number;
  response_json_schema?: object;
  images?: string[]; // Array of image URLs or base64 strings (max 3)
}

export interface ChatOptions {
  model?: string;
  temperature?: number;
  stream?: boolean;
}

export interface ImageOptions {
  model?: string;
  size?: '1024x1024' | '1792x1024' | '1024x1792';
  quality?: 'standard' | 'hd';
  n?: number;
}

export interface TranscribeOptions {
  model?: string;
  language?: string; // ISO-639-1 language code (e.g., 'en', 'es', 'fr')
  prompt?: string; // Optional text to guide the model's style
  response_format?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
  temperature?: number; // 0-1, higher values make output more random
}

export interface InvokeTextResponse {
  text: string;
}

export interface ChatResponse {
  message: {
    role: 'assistant';
    content: string;
  };
  usage: any;
}

export interface SingleImageResponse {
  url: string;
  filename: string;
  prompt: string;
  model: string;
  size: string;
  quality: string;
  downloadUrl: string;
}

export interface MultipleImageResponse {
  images: Array<{
    url: string;
    filename: string;
    downloadUrl: string;
  }>;
  prompt: string;
  model: string;
  size: string;
  count: number;
}

export interface ModelsResponse {
  text: string[];
  image: string[];
  transcription: string[];
  default: {
    text: string;
    image: string;
    transcription: string;
  };
}

export interface TranscribeResponse {
  text: string;
  language?: string;
  duration?: number; // Duration in seconds
  format?: string; // Only present for non-JSON formats
  segments?: Array<{
    id: number;
    seek: number;
    start: number;
    end: number;
    text: string;
    tokens: number[];
    temperature: number;
    avg_logprob: number;
    compression_ratio: number;
    no_speech_prob: number;
  }>; // Only present for verbose_json format
  words?: Array<{
    word: string;
    start: number;
    end: number;
  }>; // Only present for verbose_json format with word-level timestamps
}

// File Management Types
export interface FileUploadOptions {
  tags?: string[];
  metadata?: Record<string, any>;
}

export interface FileListOptions {
  limit?: number;
  skip?: number;
  tags?: string[];
  mimeType?: string;
}

export interface UploadedFile {
  _id: string;
  filename: string;
  originalName: string;
  mimeType: string;
  size: number;
  url: string;
  downloadUrl: string;
  pathname: string;
  creator: string;
  tags?: string[];
  metadata?: Record<string, any>;
  createdAt: Date;
  updatedAt: Date;
}

export interface FileListResponse {
  success: boolean;
  data: UploadedFile[];
  total: number;
  limit: number;
  skip: number;
}

export interface SDKConfig {
  projectId: string;
  apiUrl?: string;
  apiKey?: string; // API key for Cloudflare Workers and server-side usage
  debug?: boolean;
  linkingScheme?: string; // For native OAuth redirects, e.g., 'myapp://' or 'exp://'
}

export interface AuthCallbackMessage {
  type: 'magically-auth-callback';
  accessToken: string;
  user: {
    id: string;
    email: string;
    name: string;
  };
}