@unedio/types 0.0.1

package/src/types/database.types.ts

@@ -0,0 +1,375 @@
+/**
+ * Database types matching the SQL schema
+ * These types represent the structure of tables in Supabase
+ */
+
+import {
+  ApplicationSource,
+  ChangeType,
+  CustomDomainStatus,
+  EmailTemplateType,
+  JobStatus,
+  JobType,
+  SubscriptionStatus,
+  UserType,
+  WorkModality,
+  WorkspaceUserRole,
+} from './enums';
+
+// ============================================================================
+// USERS & AUTHENTICATION
+// ============================================================================
+
+export interface User {
+  id: string;
+  external_id: string;
+  email: string;
+  name: string | null;
+  type: UserType;
+  avatar_url: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SeekerProfile {
+  id: string;
+  user_id: string;
+  full_name: string | null;
+  phone: string | null;
+  linkedin_url: string | null;
+  city: string | null;
+  country: string | null;
+  summary: string | null;
+  skills: string[] | null;
+  experience_years: number | null;
+  education: Education[] | null;
+  experience: Experience[] | null;
+  updated_at: string;
+  cv_url: string | null;
+  email: string | null;
+  availability_status: 'available' | 'hired' | 'not_looking';
+  last_placed_at_client_id: string | null;
+}
+
+export interface Education {
+  institution: string;
+  degree: string;
+  field: string | null;
+  start_date: string;
+  end_date: string | null;
+}
+
+export interface Experience {
+  company: string;
+  position: string;
+  description: string;
+  start_date: string;
+  end_date: string | null;
+}
+
+// ============================================================================
+// WORKSPACES & MULTI-TENANCY
+// ============================================================================
+
+export interface Workspace {
+  id: string;
+  name: string;
+  domain: string | null;
+  subdomain: string | null;
+  custom_domain_status: CustomDomainStatus;
+  created_at: string;
+  deleted_at: string | null;
+  workspace_mode: 'company' | 'agency';
+  language: string;
+}
+
+export interface WorkspaceUser {
+  id: string;
+  workspace_id: string;
+  user_id: string;
+  role: WorkspaceUserRole;
+  created_at: string;
+}
+
+export interface WorkspaceBranding {
+  id: string;
+  workspace_id: string;
+  primary_color: string;
+  secondary_color: string;
+  font_family: string;
+  logo_url: string | null;
+  favicon_url: string | null;
+  updated_at: string;
+}
+
+// ============================================================================
+// CLIENTS & CONTACTS
+// ============================================================================
+
+export interface Client {
+  id: string;
+  workspace_id: string;
+  name: string;
+  website: string | null;
+  industry: string | null;
+  created_at: string;
+  deleted_at: string | null;
+}
+
+export interface Note {
+  id: string;
+  workspace_id: string;
+  seeker_id: string | null;
+  job_id: string | null;
+  client_id: string | null;
+  contact_id: string | null;
+  author_id: string | null;
+  content: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Contact {
+  id: string;
+  workspace_id: string;
+  client_id: string;
+  full_name: string;
+  email: string | null;
+  phone: string | null;
+  role: string | null;
+  is_primary: boolean;
+  created_at: string;
+}
+
+// ============================================================================
+// JOBS & APPLICATIONS
+// ============================================================================
+
+export interface Job {
+  id: string;
+  workspace_id: string;
+  recruiter_id: string | null;
+  title: string;
+  description: string;
+  work_modality: WorkModality | null;
+  job_type: JobType | null;
+  status: JobStatus;
+  location: string | null;
+  salary_range: string | null;
+  created_at: string;
+  deleted_at: string | null;
+  client_id: string | null;
+  contact_id: string | null;
+}
+
+export interface JobViewStats {
+  id: string;
+  job_id: string;
+  source: ApplicationSource;
+  created_at: string;
+}
+
+export interface ApplicationStatus {
+  id: string;
+  workspace_id: string;
+  status_name: string;
+  order: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface JobApplication {
+  id: string;
+  job_id: string;
+  user_id: string;
+  status_id: string | null;
+  source: ApplicationSource;
+  applied_at: string;
+  updated_at: string;
+  created_by_id: string | null;
+}
+
+export interface JobApplicationComment {
+  id: string;
+  job_application_id: string;
+  user_id: string;
+  comment_text: string;
+  created_at: string;
+}
+
+export interface JobApplicationHistory {
+  id: string;
+  job_application_id: string;
+  actor_id: string | null;
+  change_type: ChangeType;
+  old_value: string | null;
+  new_value: string | null;
+  created_at: string;
+}
+
+// ============================================================================
+// SUBSCRIPTIONS & BILLING
+// ============================================================================
+
+export interface Plan {
+  id: string;
+  name: string;
+  slug: string;
+  max_seats: number;
+  price_id_stripe: string | null;
+  created_at: string;
+}
+
+export interface Subscription {
+  id: string;
+  workspace_id: string;
+  plan_id: string;
+  stripe_subscription_id: string | null;
+  status: SubscriptionStatus;
+  current_period_end: string | null;
+  created_at: string;
+  updated_at: string;
+  stripe_customer_id: string | null;
+}
+
+// ============================================================================
+// COMMUNICATIONS
+// ============================================================================
+
+export interface EmailTemplate {
+  id: string;
+  workspace_id: string;
+  name: string;
+  subject: string;
+  body_text: string;
+  type: EmailTemplateType;
+  created_at: string;
+}
+
+export interface SavedCandidate {
+  id: string;
+  workspace_id: string;
+  seeker_id: string;
+  added_by: string | null;
+  created_at: string;
+}
+
+// ============================================================================
+// OTHER
+// ============================================================================
+
+export interface Waitlist {
+  id: string;
+  email: string;
+  created_at: string;
+}
+
+// ============================================================================
+// DATABASE TYPES (for Supabase client)
+// ============================================================================
+
+export interface Database {
+  public: {
+    Tables: {
+      users: {
+        Row: User;
+        Insert: Omit<User, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<User, 'id' | 'external_id' | 'created_at'>>;
+      };
+      seeker_profiles: {
+        Row: SeekerProfile;
+        Insert: Omit<SeekerProfile, 'id' | 'updated_at'>;
+        Update: Partial<Omit<SeekerProfile, 'id' | 'user_id'>>;
+      };
+      workspaces: {
+        Row: Workspace;
+        Insert: Omit<Workspace, 'id' | 'created_at' | 'deleted_at' | 'language'> & {
+          language?: string;
+        };
+        Update: Partial<Omit<Workspace, 'id' | 'created_at'>>;
+      };
+      workspace_users: {
+        Row: WorkspaceUser;
+        Insert: Omit<WorkspaceUser, 'id' | 'created_at'>;
+        Update: Partial<Omit<WorkspaceUser, 'id' | 'workspace_id' | 'user_id' | 'created_at'>>;
+      };
+      workspace_branding: {
+        Row: WorkspaceBranding;
+        Insert: Omit<WorkspaceBranding, 'id' | 'updated_at'>;
+        Update: Partial<Omit<WorkspaceBranding, 'id' | 'workspace_id'>>;
+      };
+      clients: {
+        Row: Client;
+        Insert: Omit<Client, 'id' | 'created_at' | 'deleted_at'>;
+        Update: Partial<Omit<Client, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      notes: {
+        Row: Note;
+        Insert: Omit<Note, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<Note, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      contacts: {
+        Row: Contact;
+        Insert: Omit<Contact, 'id' | 'created_at'>;
+        Update: Partial<Omit<Contact, 'id' | 'client_id' | 'created_at'>>;
+      };
+      jobs: {
+        Row: Job;
+        Insert: Omit<Job, 'id' | 'created_at' | 'deleted_at'>;
+        Update: Partial<Omit<Job, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      job_views_stats: {
+        Row: JobViewStats;
+        Insert: Omit<JobViewStats, 'id' | 'created_at'>;
+        Update: never; // Read-only stats
+      };
+      application_statuses: {
+        Row: ApplicationStatus;
+        Insert: Omit<ApplicationStatus, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<ApplicationStatus, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      job_applications: {
+        Row: JobApplication;
+        Insert: Omit<JobApplication, 'id' | 'applied_at' | 'updated_at'>;
+        Update: Partial<Omit<JobApplication, 'id' | 'job_id' | 'user_id' | 'applied_at'>>;
+      };
+      job_application_comments: {
+        Row: JobApplicationComment;
+        Insert: Omit<JobApplicationComment, 'id' | 'created_at'>;
+        Update: Partial<
+          Omit<JobApplicationComment, 'id' | 'job_application_id' | 'user_id' | 'created_at'>
+        >;
+      };
+      job_application_history: {
+        Row: JobApplicationHistory;
+        Insert: Omit<JobApplicationHistory, 'id' | 'created_at'>;
+        Update: never; // Immutable audit log
+      };
+      plans: {
+        Row: Plan;
+        Insert: Omit<Plan, 'id' | 'created_at'>;
+        Update: Partial<Omit<Plan, 'id' | 'slug' | 'created_at'>>;
+      };
+      subscriptions: {
+        Row: Subscription;
+        Insert: Omit<Subscription, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<Subscription, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      email_templates: {
+        Row: EmailTemplate;
+        Insert: Omit<EmailTemplate, 'id' | 'created_at'>;
+        Update: Partial<Omit<EmailTemplate, 'id' | 'workspace_id' | 'created_at'>>;
+      };
+      saved_candidates: {
+        Row: SavedCandidate;
+        Insert: Omit<SavedCandidate, 'id' | 'created_at'>;
+        Update: Partial<Omit<SavedCandidate, 'id' | 'workspace_id' | 'seeker_id' | 'created_at'>>;
+      };
+      waitlist: {
+        Row: Waitlist;
+        Insert: Omit<Waitlist, 'id' | 'created_at'>;
+        Update: never; // Insert-only table
+      };
+    };
+  };
+}

package/src/types/enums.ts

@@ -0,0 +1,62 @@
+/**
+ * Enums and constant types for the API
+ */
+
+export enum ErrorCode {
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  BAD_REQUEST = 'BAD_REQUEST',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DB_ERROR = 'DB_ERROR',
+}
+
+export type UserType = 'recruiter' | 'seeker';
+
+export type JobStatus = 'draft' | 'published' | 'archived';
+
+export type WorkModality = 'remote' | 'hybrid' | 'office';
+
+export type JobType = 'full-time' | 'part-time' | 'contractor' | 'internship';
+
+export type SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'trialing';
+
+export type CustomDomainStatus = 'not_requested' | 'pending' | 'active' | 'error';
+
+export type EmailTemplateType =
+  | 'rejection'
+  | 'interview_invite'
+  | 'offer'
+  | 'onboarding'
+  | 'general';
+
+export type WorkspaceUserRole = 'owner' | 'member';
+
+export type ApplicationSource = 'direct' | 'linkedin' | 'indeed' | 'referral' | 'other';
+
+export type ChangeType =
+  | 'status_changed'
+  | 'comment_added'
+  | 'email_sent'
+  | 'application_created'
+  | 'application_updated';
+
+export const USER_TYPES: UserType[] = ['recruiter', 'seeker'];
+export const JOB_STATUSES: JobStatus[] = ['draft', 'published', 'archived'];
+export const WORK_MODALITIES: WorkModality[] = ['remote', 'hybrid', 'office'];
+export const JOB_TYPES: JobType[] = ['full-time', 'part-time', 'contractor', 'internship'];
+export const SUBSCRIPTION_STATUSES: SubscriptionStatus[] = [
+  'active',
+  'past_due',
+  'canceled',
+  'trialing',
+];
+export const EMAIL_TEMPLATE_TYPES: EmailTemplateType[] = [
+  'rejection',
+  'interview_invite',
+  'offer',
+  'onboarding',
+  'general',
+];

package/src/types/hono.types.ts

@@ -0,0 +1,32 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { WorkspaceAccessState } from './api.types';
+import { Workspace } from './database.types';
+import { UserType, WorkspaceUserRole } from './enums';
+
+export interface HonoEnv {
+  Bindings: {
+    PRODUCTION: string;
+    COOKIE_SECRET: string;
+    SUPABASE_URL: string;
+    SUPABASE_SECRET_KEY: string;
+    AUTH0_DOMAIN: string;
+    AUTH0_CLIENT_ID: string;
+    AUTH0_CLIENT_SECRET: string;
+    GOOGLE_AI_API_KEY: string;
+    GOOGLE_AI_MODEL?: string;
+  };
+  Variables: {
+    supabase: SupabaseClient;
+    user: {
+      idToken: string;
+      accessToken: string;
+    };
+    userId: string;
+    userType: UserType;
+    validated: any;
+    workspaceId: string;
+    workspaceRole: WorkspaceUserRole | null;
+    workspace: Workspace & { role?: WorkspaceUserRole | null };
+    workspaceAccess: WorkspaceAccessState;
+  };
+}

package/src/utils/ai.ts

@@ -0,0 +1,70 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+export interface AIRequestOptions {
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface AIResponse {
+  content: string;
+  raw: any;
+}
+
+const DEFAULT_MODEL = 'gemini-3.1-flash-lite-preview';
+
+/**
+ * Sends a prompt to the AI provider with retry logic for rate limits.
+ */
+export const sendPrompt = async (
+  apiKey: string,
+  prompt: string,
+  options: AIRequestOptions = {},
+  maxRetries = 5,
+): Promise<AIResponse> => {
+  let lastError: any;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const genAI = new GoogleGenerativeAI(apiKey);
+      const modelName = options.model || DEFAULT_MODEL;
+      const model = genAI.getGenerativeModel({ model: modelName });
+
+      console.log(
+        `[AI] Sending prompt to Google AI Studio using model: ${modelName} (Attempt ${attempt + 1}/${maxRetries + 1})`,
+      );
+
+      const generationConfig = {
+        temperature: options.temperature ?? 0.1,
+        maxOutputTokens: options.maxTokens ?? 8192,
+        responseMimeType: 'application/json',
+      };
+
+      const result = await model.generateContent({
+        contents: [{ role: 'user', parts: [{ text: prompt }] }],
+        generationConfig,
+      });
+
+      const response = result.response;
+      return {
+        content: response.text(),
+        raw: response,
+      };
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle Rate Limit (429) for Google
+      if (error?.status === 429 && attempt < maxRetries) {
+        // Longer delay to respect Google's quota (often 30s-60s on free tier errors)
+        const delay = (attempt + 1) * 10000; // 10s, 20s, 30s, 40s...
+        console.warn(`[AI] Rate limit hit (429). Retrying in ${delay}ms...`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        continue;
+      }
+
+      throw error;
+    }
+  }
+
+  throw lastError;
+};

package/src/utils/email.ts

@@ -0,0 +1,26 @@
+export const EMAIL_REGEX =
+  /^[\p{L}\p{N}\p{M}!#$%&'*+/=?^_`{|}~.-]+@(?:[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?\.)+[\p{L}\p{N}](?:[\p{L}\p{N}-]{0,61}[\p{L}\p{N}])?$/u;
+
+function compactEmailSeparators(value: string): string {
+  return value.replace(/[\u00A0\u200B-\u200D\uFEFF]/gu, '').replace(/\s*@\s*/gu, '@');
+}
+
+export function normalizeEmail(value: string | null | undefined): string | null {
+  const trimmed = value?.normalize('NFC').trim();
+
+  if (!trimmed) {
+    return null;
+  }
+
+  return compactEmailSeparators(trimmed).toLowerCase();
+}
+
+export function isValidEmail(value: string | null | undefined): boolean {
+  const normalized = normalizeEmail(value);
+
+  if (!normalized) {
+    return false;
+  }
+
+  return EMAIL_REGEX.test(normalized);
+}

package/src/utils/errors.ts

@@ -0,0 +1,60 @@
+import { StatusCode } from 'hono/utils/http-status';
+import { ErrorCode } from '../types/enums';
+
+export class AppError extends Error {
+  public readonly statusCode: StatusCode;
+  public readonly code: string;
+  public readonly details?: any;
+  public readonly isOperational: boolean;
+
+  constructor(
+    message: string,
+    statusCode: StatusCode = 500,
+    code: string = ErrorCode.INTERNAL_ERROR,
+    details?: any,
+  ) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    this.isOperational = true;
+
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class BadRequestError extends AppError {
+  constructor(message = 'Bad Request', details?: any) {
+    super(message, 400, ErrorCode.BAD_REQUEST, details);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized', details?: any) {
+    super(message, 401, ErrorCode.UNAUTHORIZED, details);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = 'Forbidden', details?: any) {
+    super(message, 403, ErrorCode.FORBIDDEN, details);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = 'Not Found', details?: any) {
+    super(message, 404, ErrorCode.NOT_FOUND, details);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message = 'Conflict', details?: any) {
+    super(message, 409, ErrorCode.CONFLICT, details);
+  }
+}
+
+export class InternalServerError extends AppError {
+  constructor(message = 'Internal Server Error', details?: any) {
+    super(message, 500, ErrorCode.INTERNAL_ERROR, details);
+  }
+}

package/src/utils/json.ts

@@ -0,0 +1,26 @@
+/**
+ * Extracts and parses JSON from a string, supporting markdown code blocks.
+ */
+export const extractJSON = <T = any>(input: string): T => {
+  let jsonString = input.trim();
+
+  // Extract markdown code blocks if present (e.g., ```json ... ``` or just ``` ... ```)
+  const codeBlockMatch = input.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  if (codeBlockMatch) {
+    jsonString = codeBlockMatch[1].trim();
+  } else {
+    // Extract direct JSON object if no code blocks are found
+    const jsonMatch = input.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      jsonString = jsonMatch[0];
+    }
+  }
+
+  try {
+    return JSON.parse(jsonString) as T;
+  } catch (parseError) {
+    console.error('Error parsing JSON string:', parseError);
+    console.error('Original string:', input);
+    throw new Error('Failed to parse JSON content');
+  }
+};

package/src/utils/pagination.ts

@@ -0,0 +1,44 @@
+/**
+ * Pagination utilities
+ */
+
+import { PaginationMeta, PaginationParams } from '../types/api.types';
+
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_LIMIT = 20;
+export const MAX_LIMIT = 100;
+
+/**
+ * Parse and validate pagination parameters
+ */
+export function parsePagination(params: PaginationParams): {
+  page: number;
+  limit: number;
+  offset: number;
+} {
+  const page = Math.max(1, params.page || DEFAULT_PAGE);
+  const limit = Math.min(Math.max(1, params.limit || DEFAULT_LIMIT), MAX_LIMIT);
+  const offset = (page - 1) * limit;
+
+  return { page, limit, offset };
+}
+
+/**
+ * Build pagination metadata
+ */
+export function buildPaginationMeta(page: number, limit: number, total: number): PaginationMeta {
+  return {
+    page,
+    limit,
+    total,
+    totalPages: Math.ceil(total / limit),
+  };
+}
+
+/**
+ * Apply pagination to Supabase query
+ */
+export function applyPagination(query: any, params: PaginationParams): any {
+  const { limit, offset } = parsePagination(params);
+  return query.range(offset, offset + limit - 1);
+}