Util Server Package

Overview

@zooly/util-srv is a server-side utility package that provides common server-only functions and services used across server packages in the monorepo.

Package Details

• Package Name: @zooly/util-srv
• Location: packages/util-srv
• Type: Server-side utility library

Key Features

• S3 operations (upload, download, existence checks)
• Image upload utilities
• Embedding generation for AI/ML applications
• Structured data extraction from natural language using AI
• Server-side helper functions

S3 Utilities

The package provides comprehensive S3 functionality:

• Upload to S3: Upload buffers to S3 and get public URLs
• Get S3 Object: Download objects from S3 as byte arrays
• Check Object Exists: Verify if an S3 object exists and get its URL
• Upload Image from URL: Fetch images from URLs and upload them to S3
• S3 URL Helpers: Check if a URL is an S3 URL and build public URLs

Embedding Generation

The package provides OpenAI embedding generation functionality:

• generateEmbedding(text) - Generate embedding vectors for text content
  • Uses OpenAI's text-embedding-3-small model
  • Returns 1536-dimensional embedding vectors
  • Validates input text and embedding dimensions
  • See packages/util-srv/src/generateEmbedding.ts for implementation

Structured Data Generation

The package provides AI-powered structured data extraction from natural language:

• generateStructuredData(prompt, schema, schemaName?, schemaDescription?, output?) - Extract structured data from text using Google Gemini
  • Uses Google Gemini gemini-2.5-flash-lite model
  • Takes a natural language prompt and a Zod schema
  • Returns validated structured data matching the schema
  • Supports output modes: "object", "enum", "array", or "no-schema"
  • Automatically validates and type-checks the AI response
  • Logs warnings for empty string values in the response
  • See packages/util-srv/src/generateStructuredData.ts for implementation

Usage Example

import { generateStructuredData } from "@zooly/util-srv";
import { z } from "zod";

const schema = z.object({
  category: z.enum(["MODELS", "ACTORS", "MUSICIANS"]).optional(),
  gender: z.enum(["MALE", "FEMALE", "NON_BINARY"]).optional(),
  hairColor: z.enum(["BLONDE", "BROWN", "BLACK", "RED"]).optional(),
});

const result = await generateStructuredData(
  "Looking for a tall blonde female model in the US",
  schema,
  "SearchFilters",
  "Extract search characteristics from description"
);

// Result: { category: "MODELS", gender: "FEMALE", hairColor: "BLONDE" }

Use Cases

• Search Filter Extraction: Convert natural language search queries into structured filter objects
• Form Data Parsing: Extract structured data from user descriptions or briefs
• Tag Extraction: Parse unstructured text into validated tag objects
• Data Normalization: Convert free-form text into standardized enum values

API Endpoint

This function is also exposed via the API endpoint /api/generate-structured-data for client-side usage. The endpoint accepts a plain object schema definition (serialized Zod schema) and returns the extracted structured data.

Dependencies

• @aws-sdk/client-s3 for S3 operations
• @zooly/types for shared types
• @zooly/util for shared utilities
• nanoid for generating unique IDs
• ai, @ai-sdk/openai, and @ai-sdk/google for AI operations (embeddings and structured data generation)
• zod for schema validation

Usage

This package provides server-side utilities that can be imported by server packages in the monorepo. It's particularly useful for file storage operations and AWS integrations.

Environment Variables

The package requires the following environment variables:

• AWS_REGION - AWS region for S3 operations
• AWS_ACCESS_KEY_ID - AWS access key ID
• AWS_SECRET_ACCESS_KEY - AWS secret access key
• AWS_BUCKET_NAME - S3 bucket name
• OPENAI_API_KEY - OpenAI API key for embedding generation
• GOOGLE_GENERATIVE_AI_API_KEY - Google AI API key for structured data generation (Gemini)