API Reference

Core Functions

configureSymulate()

Configure global Symulate settings. Call this once at your application's entry point.

import { configureSymulate } from '@symulate/sdk';

configureSymulate({
  // Authentication (required)
  symulateApiKey: 'sym_live_xxx',         // Get from platform.symulate.dev
  projectId: 'proj_xxx',                  // Project ID for multi-project isolation

  // Environment
  environment: 'development',             // 'development' | 'production'
  backendBaseUrl: 'https://api.your.com', // Required for production mode

  // Generation Mode
  generateMode: 'auto',                   // 'ai' | 'faker' | 'auto' (default: 'auto')

  // Cache Settings
  cacheEnabled: true,                     // Enable caching (default: true)
  persistentCache: false,                 // Use localStorage (default: false)
  regenerateOnConfigChange: true,         // Invalidate on config change (default: true)

  // Faker Settings
  fakerSeed: 12345,                       // Deterministic generation (optional)

  // Localization (Premium)
  language: 'en',                         // Language for AI data (default: 'en')
});

defineEndpoint()

Define a mock API endpoint with schema and configuration.

import { defineEndpoint, m, type Infer } from '@symulate/sdk';

const UserSchema = m.object({
  id: m.uuid(),
  name: m.person.fullName(),
  email: m.email(),
});

export type User = Infer<typeof UserSchema>;

export const getUsers = defineEndpoint<User[]>({
  path: '/api/users',                    // API path
  method: 'GET',                         // HTTP method
  schema: UserSchema,                    // Data schema (required for generation)
  mock: {
    count: 10,                           // Number of items (default: 1)
    instruction: 'Generate developers',  // AI instruction (optional)
    delay: 500,                          // Simulated delay in ms (optional)
  },
  params: {},                            // Optional default params
  mode: 'mock',                          // Override global environment (optional)
});

getConfig()

Retrieve the current global configuration.

import { getConfig } from '@symulate/sdk';

const config = getConfig();
console.log(config.environment); // 'development' | 'production'

clearCache()

Clear all cached mock data.

import { clearCache } from '@symulate/sdk';

// Clear all cache
await clearCache();

// Clear cache for specific API key
await clearCache('api_key_id');

getRegisteredEndpoints()

Get all registered endpoints in your application.

import { getRegisteredEndpoints } from '@symulate/sdk';

const endpoints = getRegisteredEndpoints();
// Map<string, EndpointConfig> with keys like "GET /api/users"

Configuration

MockendConfig Interface

Complete configuration options for configureSymulate().

Generation Modes

generateMode: 'ai'

generateMode: 'faker'

generateMode: 'auto'

Schema Builder (m)

The m object provides a fluent API for defining your data schemas with type safety and AI-friendly semantic information.

Primitive Types

Basic data types. All accept an optional description parameter for AI context.

m.string(description?)       // Random string
m.number(description?)       // Random number
m.boolean(description?)      // Random boolean
m.uuid(description?)         // UUID v4
m.date(description?)         // ISO 8601 date
m.email(description?)        // Email address
m.url(description?)          // Valid URL
m.phoneNumber(description?)  // Phone number

// Example with descriptions
const schema = m.object({
  id: m.uuid(),
  bio: m.string('Professional biography'),
  age: m.number('Age between 18-65'),
  verified: m.boolean(),
});

Person Fields

Generate realistic person-related data.

m.person.fullName(description?)   // Full name
m.person.firstName(description?)  // First name only
m.person.lastName(description?)   // Last name only
m.person.jobTitle(description?)   // Job title/position

// Example
const TeamMemberSchema = m.object({
  name: m.person.fullName('Tech industry professional'),
  role: m.person.jobTitle('Engineering role'),
});

Internet Fields

Generate internet and web-related data.

m.internet.userName(description?)  // Username/handle
m.internet.avatar(description?)    // Avatar image URL

// Example
const ProfileSchema = m.object({
  username: m.internet.userName(),
  avatar: m.internet.avatar(),
  website: m.url(),
  email: m.email(),
});

Location Fields

Generate address and location data.

m.location.street(description?)    // Street address
m.location.city(description?)      // City name
m.location.state(description?)     // State/province
m.location.zipCode(description?)   // ZIP/postal code
m.location.country(description?)   // Country name
m.location.latitude(description?)  // Latitude coordinate
m.location.longitude(description?) // Longitude coordinate

// Example
const AddressSchema = m.object({
  street: m.location.street(),
  city: m.location.city(),
  state: m.location.state(),
  zipCode: m.location.zipCode(),
  country: m.location.country(),
  coordinates: m.object({
    lat: m.location.latitude(),
    lng: m.location.longitude(),
  }),
});

Commerce Fields

Generate e-commerce and product data.

m.commerce.productName(description?)  // Product name
m.commerce.department(description?)   // Department/category
m.commerce.price(description?)        // Price (number)

// Example
const ProductSchema = m.object({
  name: m.commerce.productName('Electronics'),
  category: m.commerce.department(),
  price: m.commerce.price('Price between $10-$1000'),
});

Lorem Text

Generate placeholder text content.

m.lorem.word(description?)       // Single word
m.lorem.sentence(description?)   // Single sentence
m.lorem.paragraph(description?)  // Paragraph

// Example
const ArticleSchema = m.object({
  title: m.lorem.sentence('Article headline'),
  summary: m.lorem.paragraph('Brief summary'),
  tags: m.array(m.lorem.word()),
});

Complex Types

Objects

Create structured object schemas with full type inference.

m.object<T>(shape: T, description?: string)

// Example
const UserSchema = m.object({
  id: m.uuid(),
  name: m.person.fullName(),
  profile: m.object({
    bio: m.lorem.paragraph(),
    avatar: m.internet.avatar(),
  }),
}, 'Complete user profile');

type User = Infer<typeof UserSchema>;
// {
//   id: string;
//   name: string;
//   profile: {
//     bio: string;
//     avatar: string;
//   };
// }

Arrays

Create array schemas with typed elements.

m.array<T>(element: T, description?: string)

// Simple array
const TagsSchema = m.array(m.lorem.word());
type Tags = Infer<typeof TagsSchema>;  // string[]

// Array of objects
const CommentsSchema = m.array(
  m.object({
    author: m.person.fullName(),
    text: m.lorem.paragraph(),
  })
);
type Comments = Infer<typeof CommentsSchema>;
// { author: string; text: string; }[]

Endpoint Configuration

Complete options for defineEndpoint().

HTTP Methods

// GET - Fetch data
export const getUsers = defineEndpoint<User[]>({
  path: '/api/users',
  method: 'GET',
  schema: UserSchema,
});

// POST - Create data
export const createUser = defineEndpoint<User>({
  path: '/api/users',
  method: 'POST',
  schema: UserSchema,
});

// PUT - Update data
export const updateUser = defineEndpoint<User>({
  path: '/api/users/:id',
  method: 'PUT',
  schema: UserSchema,
});

// DELETE - Remove data
export const deleteUser = defineEndpoint<void>({
  path: '/api/users/:id',
  method: 'DELETE',
});

Parameters

Define typed parameters for your endpoints with automatic validation and proper routing in both mock and production modes.

Parameter Locations

Parameters can be defined in four locations:

Basic Example

const getUserById = defineEndpoint({
  path: '/api/users/:id',
  method: 'GET',
  params: [
    {
      name: 'id',
      location: 'path',
      required: true,
      schema: m.uuid(),
      description: 'The unique identifier of the user',
    },
  ],
  schema: m.object({
    id: m.uuid(),
    name: m.string(),
    email: m.email(),
  }),
});

// Usage - parameters are validated
const user = await getUserById({ id: '123e4567-e89b-12d3-a456-426614174000' });

Query Parameters

Add query parameters for filtering, pagination, and sorting:

const listUsers = defineEndpoint({
  path: '/api/users',
  method: 'GET',
  params: [
    {
      name: 'page',
      location: 'query',
      required: false,
      schema: m.number(),
      description: 'Page number for pagination',
      example: 1,
    },
    {
      name: 'limit',
      location: 'query',
      required: false,
      schema: m.number(),
      description: 'Number of items per page',
      example: 10,
    },
    {
      name: 'search',
      location: 'query',
      required: false,
      schema: m.string(),
      description: 'Search term to filter users',
      example: 'john',
    },
  ],
  schema: m.object({
    id: m.uuid(),
    name: m.string(),
    email: m.email(),
  }),
  mock: { count: 10 },
});

// Optional parameters
const users = await listUsers({ page: 1, limit: 20, search: 'john' });

Header Parameters

Define header parameters for authentication and API keys:

const getProtectedResource = defineEndpoint({
  path: '/api/protected/data',
  method: 'GET',
  params: [
    {
      name: 'Authorization',
      location: 'header',
      required: true,
      schema: m.string(),
      description: 'Bearer token for authentication',
      example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    },
    {
      name: 'X-API-Key',
      location: 'header',
      required: false,
      schema: m.string(),
      description: 'Optional API key for additional security',
    },
  ],
  schema: m.object({
    data: m.string(),
    timestamp: m.date(),
  }),
});

// Usage
const data = await getProtectedResource({
  Authorization: 'Bearer token-123',
  'X-API-Key': 'api-key-456',
});

Body Parameters

Define body parameters for POST, PUT, and PATCH requests:

const createUser = defineEndpoint({
  path: '/api/users',
  method: 'POST',
  params: [
    {
      name: 'name',
      location: 'body',
      required: true,
      schema: m.string(),
      description: 'User name',
    },
    {
      name: 'email',
      location: 'body',
      required: true,
      schema: m.email(),
      description: 'User email',
    },
    {
      name: 'role',
      location: 'body',
      required: false,
      schema: m.string(),
      description: 'User role (defaults to "user")',
      example: 'admin',
    },
  ],
  schema: m.object({
    id: m.uuid(),
    name: m.string(),
    email: m.email(),
    role: m.string(),
  }),
});

// Usage
const newUser = await createUser({
  name: 'John Doe',
  email: 'john@example.com',
  role: 'admin',
});

Mixed Parameters

Combine all parameter types in a single endpoint:

const createOffer = defineEndpoint({
  path: '/api/organizations/:orgId/offers',
  method: 'POST',
  params: [
    {
      name: 'orgId',
      location: 'path',
      required: true,
      schema: m.uuid(),
      description: 'Organization ID',
    },
    {
      name: 'notify',
      location: 'query',
      required: false,
      schema: m.boolean(),
      description: 'Send notification email',
      example: true,
    },
    {
      name: 'Authorization',
      location: 'header',
      required: true,
      schema: m.string(),
      description: 'Bearer token',
    },
    {
      name: 'customer_name',
      location: 'body',
      required: true,
      schema: m.string(),
      description: 'Customer name',
    },
    {
      name: 'amount',
      location: 'body',
      required: true,
      schema: m.number(),
      description: 'Offer amount',
    },
  ],
  schema: m.object({
    id: m.uuid(),
    customer_name: m.string(),
    amount: m.number(),
    status: m.string(),
    created_at: m.date(),
  }),
});

// Usage
const offer = await createOffer({
  orgId: 'org-123',                // → Path: /api/organizations/org-123/offers
  notify: true,                    // → Query: ?notify=true
  Authorization: 'Bearer token',   // → Header: Authorization: Bearer token
  customer_name: 'Acme Corp',      // → Body: { "customer_name": "Acme Corp", "amount": 5000 }
  amount: 5000,
});

POST /api/organizations/org-123/offers?notify=true
Headers:
  Authorization: Bearer token
  Content-Type: application/json
Body:
  { "customer_name": "Acme Corp", "amount": 5000 }

Parameter Validation

Required parameters are enforced at runtime:

const searchProducts = defineEndpoint({
  path: '/api/products/search',
  method: 'GET',
  params: [
    {
      name: 'q',
      location: 'query',
      required: true,  // Required parameter
      schema: m.string(),
      description: 'Search query',
    },
    {
      name: 'category',
      location: 'query',
      required: false,  // Optional parameter
      schema: m.string(),
      description: 'Filter by category',
    },
  ],
  schema: m.object({
    id: m.uuid(),
    name: m.string(),
    price: m.number(),
  }),
  mock: { count: 15 },
});

// This works - required parameter provided
const products = await searchProducts({ q: 'laptop', category: 'electronics' });

// This throws an error - missing required 'q' parameter
try {
  await searchProducts({ category: 'electronics' });
} catch (error) {
  console.error(error);
  // Error: [Symulate] Missing required parameters for GET /api/products/search: q (query)
}

Parameter Config Properties

Path Parameters (Legacy)

You can also use path parameters without explicit parameter definitions (legacy behavior):

// Define with :param syntax
export const getUser = defineEndpoint<User>({
  path: '/api/users/:id',
  method: 'GET',
  schema: UserSchema,
});

// Call with parameters
const user = await getUser({ id: '123' });

// Multiple parameters
export const getComment = defineEndpoint<Comment>({
  path: '/api/posts/:postId/comments/:commentId',
  method: 'GET',
  schema: CommentSchema,
});

await getComment({ postId: 'abc', commentId: 'xyz' });

Error Responses

Define custom error responses for endpoints. These will be included in the OpenAPI specification and can be used for testing error states.

// Basic error configuration
export const getUser = defineEndpoint<User>({
  path: '/api/users/:id',
  method: 'GET',
  schema: UserSchema,
  errors: [
    {
      code: 404,
      description: 'User not found',
      schema: m.object({
        error: m.object({
          message: m.string(),
          code: m.string(),
          userId: m.uuid(),
        }),
      }),
    },
    {
      code: 403,
      description: 'Insufficient permissions',
      schema: m.object({
        error: m.object({
          message: m.string(),
          requiredPermission: m.string(),
        }),
      }),
    },
  ],
});

Testing Error States

Use the failNow flag to simulate error responses during development:

export const createUser = defineEndpoint<User>({
  path: '/api/users',
  method: 'POST',
  schema: UserSchema,
  errors: [
    {
      code: 400,
      description: 'Validation error',
      schema: m.object({
        error: m.object({
          message: m.string(),
          validationErrors: m.array(
            m.object({
              field: m.string(),
              message: m.string(),
            })
          ),
        }),
      }),
      failNow: true, // Request will fail with this error
    },
  ],
});

Mock Configuration

Options for the mock property in endpoint configuration.

// Basic usage
mock: {
  count: 10,
}

// With AI instructions
mock: {
  count: 20,
  instruction: 'Generate diverse software engineers from tech startups',
}

// With network delay simulation
mock: {
  count: 5,
  delay: 800, // 800ms delay for testing loading states
}

// Complete example
export const getProducts = defineEndpoint<Product[]>({
  path: '/api/products',
  method: 'GET',
  schema: ProductSchema,
  mock: {
    count: 50,
    instruction: 'Generate premium electronics and gadgets',
    delay: 500,
  },
});

Type Inference

Extract TypeScript types from your schemas using the Infer utility.

import { type Infer } from '@symulate/sdk';

// Define schema
const ProductSchema = m.object({
  id: m.uuid(),
  name: m.commerce.productName(),
  price: m.commerce.price(),
  inStock: m.boolean(),
  tags: m.array(m.lorem.word()),
});

// Infer type
type Product = Infer<typeof ProductSchema>;
// Result:
// {
//   id: string;
//   name: string;
//   price: number;
//   inStock: boolean;
//   tags: string[];
// }

// Use in functions
function displayProduct(product: Product) {
  console.log(product.name); // Fully typed!
}

// Works with nested objects
const UserSchema = m.object({
  id: m.uuid(),
  profile: m.object({
    bio: m.lorem.paragraph(),
    links: m.array(m.url()),
  }),
});

type User = Infer<typeof UserSchema>;
// {
//   id: string;
//   profile: {
//     bio: string;
//     links: string[];
//   };
// }

Cache Management

Functions for managing cached mock data.

clearCache()

import { clearCache } from '@symulate/sdk';

// Clear all cached data
await clearCache();

// Clear cache for specific API key
await clearCache('api_key_id');

CLI Commands

# List all cached endpoints
npx mockend cache

# Show specific cache entry
npx mockend cache --hash abc123xyz

# Search cache entries
npx mockend cache --search users

# Clear all cache
npx mockend regenerate

# Clear specific entry
npx mockend regenerate --hash abc123xyz

# Clear entries matching pattern
npx mockend regenerate --endpoint users

Cache Behavior

Complete Examples

E-Commerce API

import { defineEndpoint, m, type Infer } from '@symulate/sdk';

// Product schema
const ProductSchema = m.object({
  id: m.uuid(),
  name: m.commerce.productName(),
  description: m.lorem.paragraph('Product description'),
  price: m.commerce.price('Price between $10-$1000'),
  category: m.commerce.department(),
  inStock: m.boolean(),
  rating: m.number('Rating 1-5'),
  images: m.array(m.url()),
  reviews: m.array(
    m.object({
      id: m.uuid(),
      author: m.person.fullName(),
      rating: m.number('Rating 1-5'),
      comment: m.lorem.paragraph(),
      date: m.date(),
    })
  ),
});

export type Product = Infer<typeof ProductSchema>;

// Endpoints
export const getProducts = defineEndpoint<Product[]>({
  path: '/api/products',
  method: 'GET',
  schema: ProductSchema,
  mock: {
    count: 20,
    instruction: 'Generate tech gadgets and electronics',
  },
});

export const getProduct = defineEndpoint<Product>({
  path: '/api/products/:id',
  method: 'GET',
  schema: ProductSchema,
});

export const createProduct = defineEndpoint<Product>({
  path: '/api/products',
  method: 'POST',
  schema: ProductSchema,
});

// Usage
const products = await getProducts();
const product = await getProduct({ id: '123' });
const newProduct = await createProduct({ name: 'New Product', ... });

Social Media API

// User schema
const UserSchema = m.object({
  id: m.uuid(),
  username: m.internet.userName(),
  fullName: m.person.fullName(),
  email: m.email(),
  avatar: m.internet.avatar(),
  bio: m.lorem.paragraph('User biography'),
  followers: m.number('Follower count'),
  following: m.number('Following count'),
});

// Post schema
const PostSchema = m.object({
  id: m.uuid(),
  author: UserSchema,
  content: m.lorem.paragraph('Post content'),
  images: m.array(m.url()),
  likes: m.number('Like count'),
  comments: m.number('Comment count'),
  createdAt: m.date(),
  tags: m.array(m.lorem.word()),
});

export type User = Infer<typeof UserSchema>;
export type Post = Infer<typeof PostSchema>;

// Endpoints
export const getPosts = defineEndpoint<Post[]>({
  path: '/api/posts',
  method: 'GET',
  schema: PostSchema,
  mock: {
    count: 30,
    instruction: 'Generate social media posts about tech and startups',
  },
});

export const getUserPosts = defineEndpoint<Post[]>({
  path: '/api/users/:userId/posts',
  method: 'GET',
  schema: PostSchema,
  mock: {
    count: 15,
  },
});