@fenaura/sdk 0.2.0

package/js/fenaura-client.d.ts

@@ -0,0 +1,376 @@
+/**
+ * Fenaura Client SDK - TypeScript Types
+ */
+
+// ─── Query Operations ────────────────────────────────────────────────────────
+
+type QueryOperation =
+  | 'select'
+  | 'insert'
+  | 'update'
+  | 'upsert'
+  | 'delete'
+  | 'rpc';
+
+// ─── Filter Operations ───────────────────────────────────────────────────────
+
+type FilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'like'
+  | 'ilike'
+  | 'in'
+  | 'is'
+  | 'contains'
+  | 'containedBy'
+  | 'overlaps'
+  | 'textSearch'
+  | 'not'
+  | 'or';
+
+// ─── Filter Types ────────────────────────────────────────────────────────────
+
+interface Filter {
+  column?: string;
+  op: FilterOperator;
+  value?: any;
+  filter?: Filter;
+  filters?: Filter[];
+}
+
+// ─── Order Types ─────────────────────────────────────────────────────────────
+
+interface Order {
+  column: string;
+  ascending?: boolean;
+}
+
+// ─── Request Types ───────────────────────────────────────────────────────────
+
+interface DataRequest {
+  op: QueryOperation;
+  table: string;
+  columns?: string;
+  filters?: Filter[];
+  order?: Order;
+  limit?: number;
+  offset?: number;
+  count?: 'exact' | 'planned' | 'estimated';
+  single?: boolean;
+  returning?: string;
+  data?: Record<string, any> | Record<string, any>[];
+  function?: string;
+  args?: Record<string, any>;
+}
+
+// ─── Response Types ──────────────────────────────────────────────────────────
+
+interface QuerySuccess {
+  status: 'success';
+  data: any;
+  count?: number;
+  request_id: string;
+}
+
+interface QueryError {
+  status: 'error';
+  data: null;
+  error: {
+    code: string;
+    message: string;
+    details?: any;
+  };
+  request_id: string;
+}
+
+type QueryResult = QuerySuccess | QueryError;
+
+// ─── Auth Types ──────────────────────────────────────────────────────────────
+
+interface SignUpParams {
+  email: string;
+  password: string;
+}
+
+interface SignInParams {
+  email: string;
+  password: string;
+}
+
+interface AuthResult {
+  status: 'success' | 'error';
+  data: {
+    session?: {
+      access_token: string;
+      refresh_token: string;
+      expires_in: number;
+      token_type: string;
+    };
+    user?: {
+      id: string;
+      email: string;
+      role: string;
+      created_at: string;
+    };
+  } | null;
+  error?: {
+    code: string;
+    message: string;
+  };
+  request_id: string;
+}
+
+// ─── Compression Types ───────────────────────────────────────────────────────
+
+type CompressMode = 'auto' | 'image' | 'gzip' | 'deflate' | 'deflate-raw' | 'none';
+type CompressImageFormat = 'original' | 'webp' | 'jpeg' | 'png';
+
+interface CompressOptions {
+  /** 'auto' (images→canvas, rest→gzip) | 'image' | 'gzip' | 'deflate' | 'deflate-raw' | 'none' (default: 'auto') */
+  mode?: CompressMode;
+  /** Max width px, aspect preserved, never upscales (default: 1920, integer 1-8192) */
+  maxWidth?: number;
+  /** Max height px (default: 1920, integer 1-8192) */
+  maxHeight?: number;
+  /** Quality (0,1] for jpeg/webp (default: 0.8; ignored for png/lossless) */
+  quality?: number;
+  /** Output image format (default: 'original'). Actual bytes rule: reported type is always the real output type. */
+  format?: CompressImageFormat;
+  /** Force lossless PNG for images (default: false) */
+  lossless?: boolean;
+  /** Keep output even when >= input (default: false → returns original) */
+  force?: boolean;
+  /** Abort compression */
+  signal?: AbortSignal;
+}
+
+interface CompressResult {
+  /** Bytes to upload (original Blob when nothing gained and force:false) */
+  file: Blob;
+  /** False when the original was kept */
+  compressed: boolean;
+  /** Applied backend: 'image'|'gzip'|'deflate'|'deflate-raw'|'none' */
+  mode: string;
+  originalSize: number;
+  compressedSize: number;
+  /** Real MIME of `file` — never assumed, always the produced bytes' type */
+  contentType: string;
+}
+
+// ─── Storage Types ───────────────────────────────────────────────────────────
+
+interface UploadOptions {
+  contentType?: string;
+  upsert?: boolean;
+  /** Client-side cap applied AFTER compression (default: 50 MiB) */
+  maxSize?: number;
+  /** true = defaults, or full CompressOptions. Compressed bytes are uploaded; success data carries compression:{mode,original_size,compressed_size}. */
+  compress?: boolean | CompressOptions;
+  onProgress?: (p: { sentBytes: number; totalBytes: number; chunksDone: number; chunksTotal: number; index: number }) => void;
+  signal?: AbortSignal;
+}
+
+interface ListOptions {
+  limit?: number;
+  offset?: number;
+}
+
+interface FileObject {
+  name: string;
+  id: string;
+  updated_at: string;
+  created_at: string;
+  last_accessed_at: string;
+  metadata: Record<string, any>;
+}
+
+interface StorageFileResponse {
+  path: string;
+  id: string;
+}
+
+// ─── Client Types ────────────────────────────────────────────────────────────
+
+interface ClientOptions {
+  /** Postgres schema to query (default: public) */
+  schema?: string;
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number;
+  /** Use same-domain proxy (default: auto). Set to '/fenaura' or true to force cookie mode via proxy, false to force direct Bearer. */
+  proxy?: boolean | string;
+  /** Alias for proxy path (e.g. '/fenaura') */
+  proxyPath?: string;
+}
+
+interface FenauraClient {
+  from<T = Record<string, any>>(table: string): QueryBuilder<T>;
+  schema(schema: string): FenauraClient;
+  rpc<T = any>(fn: string, args?: Record<string, any>, options?: { count?: boolean; get?: boolean; head?: boolean }): Promise<QueryResult & { data: T }>;
+  auth: AuthClient;
+  storage: StorageClient;
+  channel(name: string): Channel;
+  setSession(token: string): void;
+  getSession(): string | null;
+}
+
+// ─── Query Builder Types ─────────────────────────────────────────────────────
+
+interface QueryBuilder<T = Record<string, any>> {
+  select(columns?: string): QueryBuilder<T>;
+  insert(data: T | T[]): Promise<QueryResult & { data: T[] }>;
+  update(data: Partial<T>): QueryBuilder<T>;
+  /** Single object only — arrays are rejected 400 server-side. */
+  upsert(data: T): Promise<QueryResult & { data: T[] }>;
+  delete(): QueryBuilder<T>;
+
+  eq(column: keyof T, value: any): QueryBuilder<T>;
+  neq(column: keyof T, value: any): QueryBuilder<T>;
+  gt(column: keyof T, value: any): QueryBuilder<T>;
+  gte(column: keyof T, value: any): QueryBuilder<T>;
+  lt(column: keyof T, value: any): QueryBuilder<T>;
+  lte(column: keyof T, value: any): QueryBuilder<T>;
+  like(column: keyof T, pattern: string): QueryBuilder<T>;
+  ilike(column: keyof T, pattern: string): QueryBuilder<T>;
+  in(column: keyof T, values: any[]): QueryBuilder<T>;
+  is(column: keyof T, value: null): QueryBuilder<T>;
+  contains(column: keyof T, value: any): QueryBuilder<T>;
+  containedBy(column: keyof T, value: any): QueryBuilder<T>;
+  overlaps(column: keyof T, value: any): QueryBuilder<T>;
+  textSearch(column: keyof T, query: string): QueryBuilder<T>;
+  not(filter: Filter): QueryBuilder<T>;
+  or(filters: Filter[]): QueryBuilder<T>;
+
+  order(column: keyof T, options?: { ascending?: boolean }): QueryBuilder<T>;
+  limit(count: number): QueryBuilder<T>;
+  offset(count: number): QueryBuilder<T>;
+  single(): Promise<T | null>;
+  maybeSingle(): Promise<T | null>;
+  count(mode?: 'exact' | 'planned' | 'estimated'): QueryBuilder<T>;
+  returning(columns: string): QueryBuilder<T>;
+}
+
+// ─── Auth Client Types ───────────────────────────────────────────────────────
+
+type OAuthProvider = 'google' | 'github' | 'microsoft' | 'apple' | 'facebook' | 'twitter' | 'discord' | 'linkedin' | 'spotify' | 'slack' | 'gitlab' | 'twitch';
+
+interface OAuthSignInOptions {
+  redirectTo?: string;
+  scopes?: string;
+  queryParams?: Record<string, string>;
+  skipBrowserRedirect?: boolean;
+  browser?: boolean;
+}
+
+interface OAuthUrlResult {
+  status: string;
+  data: { url: string; provider: OAuthProvider } | null;
+  error: { message: string; hint?: string } | null;
+  request_id?: string;
+}
+
+interface AuthOptions {
+  browser?: boolean;
+}
+
+interface AuthClient {
+  signUp(params: SignUpParams, options?: AuthOptions): Promise<AuthResult>;
+  signIn(params: SignInParams, options?: AuthOptions): Promise<AuthResult>;
+  signOut(): Promise<QueryResult>;
+  getSession(): Promise<AuthResult>;
+  getUser(): Promise<AuthResult>;
+  signInWithOAuth(provider: OAuthProvider, options?: OAuthSignInOptions): Promise<OAuthUrlResult>;
+  sendVerificationCode(params: { email: string }): Promise<QueryResult>;
+  submitVerificationCode(params: { email: string; code: string }, options?: AuthOptions): Promise<AuthResult>;
+  sendPasswordReset(params: { email: string }): Promise<QueryResult>;
+  confirmPasswordReset(params: { email: string; code: string; newPassword: string }, options?: AuthOptions): Promise<AuthResult>;
+  sendMagicLink(params: { email: string }): Promise<QueryResult>;
+  verifyMagicCode(params: { email: string; code: string }, options?: AuthOptions): Promise<AuthResult>;
+  exchangeCodeForSession(code: string): Promise<QueryResult & { data: { token: string; project_id: string } | null }>;
+  handleOAuthCallback(): Promise<AuthResult>;
+  onAuthStateChange(callback: (event: string, session: any) => void): {
+    data: {
+      subscription: {
+        unsubscribe(): void;
+      };
+    };
+  };
+}
+
+// ─── Storage Client Types ────────────────────────────────────────────────────
+
+interface StorageClient {
+  from(bucket: string): StorageBucket;
+}
+
+interface StorageBucket {
+  upload(path: string, file: File | Blob, options?: UploadOptions): Promise<QueryResult & { data: StorageFileResponse }>;
+  download(path: string): Promise<QueryResult & { data: Blob }>;
+  list(path?: string, options?: ListOptions): Promise<QueryResult & { data: FileObject[] }>;
+  remove(paths: string[]): Promise<QueryResult>;
+  /** Same-origin SESSION url (not public — GET needs the caller's cookie). Segments encoded. Outsiders: createSignedUrl. */
+  getPublicUrl(path: string): string;
+  /** Real HMAC-signed expiring link (server-enforced, ≤7d). Anonymous fetches OK until exp. */
+  createSignedUrl(path: string, expiresIn?: number): Promise<QueryResult & { data: { signedUrl: string } }>;
+}
+
+// ─── Channel Types (Placeholder) ─────────────────────────────────────────────
+
+interface Channel {
+  on(event: string, filter: any, callback: (payload: any) => void): Channel;
+  subscribe(callback?: (status: string) => void): Channel;
+  unsubscribe(): Channel;
+}
+
+// ─── Export ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a Fenaura client. After `npx @fenaura/sdk init`, use the proxy for cookies:
+ * `createClient('/fenaura', apiKey)` or `createClient(url, apiKey, { proxy: '/fenaura' })`.
+ * Direct mode: `createClient('https://api.fenaura.com', apiKey)` uses Bearer token.
+ */
+export declare function createClient(
+  url: string,
+  apiKey: string,
+  options?: ClientOptions
+): FenauraClient;
+
+/**
+ * Compress a file on-device before upload. See CompressOptions.
+ * `compressFile.supports()` reports `{ image, gzip }` backend availability.
+ */
+export declare function compressFile(
+  file: Blob,
+  options?: CompressOptions | boolean
+): Promise<CompressResult>;
+
+export declare namespace compressFile {
+  function supports(): { image: boolean; gzip: boolean };
+}
+
+export type {
+  ClientOptions,
+  FenauraClient,
+  QueryBuilder,
+  AuthClient,
+  StorageClient,
+  StorageBucket,
+  Channel,
+  QueryResult,
+  QuerySuccess,
+  QueryError,
+  AuthResult,
+  Filter,
+  FilterOperator,
+  Order,
+  FileObject,
+  UploadOptions,
+  ListOptions,
+  CompressOptions,
+  CompressResult,
+  CompressMode,
+  CompressImageFormat,
+};