Breaking Changes

# Lilith
Authorization: Bearer {lilith_token}
X-Lilith-API-Key: {api_key}

# Yemaya
Authorization: Bearer {yemaya_token}
X-API-Key: {api_key}

# All domains use unified format
Authorization: Bearer {oshun_jwt}
# OR
Authorization: ApiKey {oshun_api_key}
# OR
X-API-Key: {oshun_api_key}

// Old
const headers = {
  'X-Lilith-API-Key': process.env.LILITH_API_KEY,
};

// New
const headers = {
  Authorization: `ApiKey ${process.env.OSHUN_API_KEY}`,
};

# Lilith
https://api.lilith.io/v1/meditations
https://api.lilith.io/v1/users

# Yemaya
https://api.yemaya.studio/projects
https://api.yemaya.studio/assets

# Unified gateway with domain prefixes
https://api.oshun.io/lilith/v1/meditations
https://api.oshun.io/lilith/v1/users

https://api.oshun.io/yemaya/v1/projects
https://api.oshun.io/yemaya/v1/assets

# New domains
https://api.oshun.io/isis/v1/generation
https://api.oshun.io/sophia/v1/search
https://api.oshun.io/hathor/v1/worlds
https://api.oshun.io/bellona/v1/exports

// Old
const LILITH_API = 'https://api.lilith.io/v1';
const response = await fetch(`${LILITH_API}/meditations`);

// New
const OSHUN_API = 'https://api.oshun.io';
const response = await fetch(`${OSHUN_API}/lilith/v1/meditations`);

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": { "page": 1, "total": 100 }
}

{
  "result": { ... },
  "status": "ok",
  "pagination": { ... }
}

// Success response
{
  "data": { ... },
  "meta": {
    "pagination": { "page": 1, "pageSize": 20, "total": 100 },
    "requestId": "req_abc123"
  }
}

// Error response
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Meditation not found",
    "details": { "id": "med-123" },
    "requestId": "req_abc123"
  }
}

// Old (Lilith)
const response = await fetch(url);
const { success, data, error } = await response.json();
if (!success) throw new Error(error);

// Old (Yemaya)
const response = await fetch(url);
const { result, status } = await response.json();
if (status !== 'ok') throw new Error('Request failed');

// New (All)
const response = await fetch(url);
const json = await response.json();
if (json.error) {
  throw new ApiError(json.error.code, json.error.message);
}
return json.data;

# Lilith
?page=1&limit=20

# Yemaya
?offset=0&count=20

# Unified
?page=1&pageSize=20
# OR cursor-based
?cursor=abc123&pageSize=20

{
  "data": [...],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5,
      "hasNext": true,
      "hasPrev": false,
      "nextCursor": "eyJpZCI6MTAwfQ=="
    }
  }
}

// Lilith
{ "error": "MEDITATION_NOT_FOUND" }
{ "error": { "code": 404, "message": "Not found" } }

// Yemaya
{ "error": "project_not_found" }
{ "status": "error", "message": "Project not found" }

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found",
    "details": {
      "resourceType": "meditation",
      "resourceId": "med-123"
    }
  }
}

// Lilith SDK
import { LilithClient } from '@lilith/sdk';
const client = new LilithClient({
  apiKey: 'your-api-key',
  environment: 'production',
});

// Yemaya SDK
import Yemaya from 'yemaya-sdk';
const client = Yemaya.init({
  key: 'your-api-key',
});

// All SDKs use factory functions
import { createLilithClient } from '@lilith/sdk';
import { createYemayaClient } from '@yemaya/sdk';
import { createIsisClient } from '@isis/client';

const lilith = createLilithClient({
  baseUrl: 'https://api.oshun.io/lilith',
  auth: {
    type: 'api-key',
    credentials: 'your-api-key',
  },
});

const yemaya = createYemayaClient({
  baseUrl: 'https://api.oshun.io/yemaya',
  auth: {
    type: 'api-key',
    credentials: 'your-api-key',
  },
});

// Lilith - mixed conventions
await client.getMeditation(id);
await client.meditation.fetch(id);
await client.fetchMeditation(id);

// Yemaya - snake_case in some places
await client.get_project(id);
await client.projects.getById(id);

// Consistent resource.action() pattern
await lilith.meditations.get(id);
await lilith.meditations.list({ page: 1 });
await lilith.meditations.create(data);
await lilith.meditations.update(id, data);
await lilith.meditations.delete(id);

await yemaya.projects.get(id);
await yemaya.projects.list();
await yemaya.projects.create(data);

// Lilith supported callbacks
client.getMeditation(id, (err, meditation) => {
  if (err) console.error(err);
  else console.log(meditation);
});

// Promises only (use async/await)
const meditation = await lilith.meditations.get(id);

// For error handling
try {
  const meditation = await lilith.meditations.get(id);
} catch (error) {
  if (error instanceof NotFoundError) {
    // Handle not found
  }
}

// Loose typing
interface Meditation {
  id: string;
  title: any;
  data: object;
}

// Strict Zod-validated types
import { z } from 'zod';

export const MeditationSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(1).max(200),
  description: z.string().optional(),
  duration: z.number().positive(),
  audioUrl: z.string().url().optional(),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
});

export type Meditation = z.infer<typeof MeditationSchema>;

// Lilith events
{
  "event": "meditation.completed",
  "userId": "user-123",
  "timestamp": 1704067200000
}

// Yemaya events
{
  "type": "project_created",
  "data": { "projectId": "proj-123" },
  "time": "2024-01-15T10:30:00Z"
}

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "lilith.meditation.completed",
  "source": "lilith",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "correlationId": "req_abc123",
  "payload": {
    "meditationId": "med-123",
    "userId": "user-456",
    "duration": 600
  },
  "metadata": {
    "environment": "production",
    "version": "1.0.0"
  }
}

// Lilith
redis.subscribe('meditation:completed', handler);

// Yemaya
bullMQ.on('completed', handler);

import { EventBus } from '@oshun/event-bus';

const eventBus = new EventBus({
  redis: { url: process.env.REDIS_URL },
  consumerGroup: 'my-service',
});

// Pattern subscription
eventBus.subscribe('lilith.meditation.*', handler);

// Specific event
eventBus.subscribe('lilith.meditation.completed', handler);

await eventBus.start();

lilith-db    → all tables
yemaya-db    → all tables

oshun-db
  ├── oshun_auth    → users, sessions, permissions
  ├── lilith        → meditations, progress, achievements
  ├── yemaya        → projects, assets, teams
  ├── isis          → generation_jobs, assets
  ├── sophia        → documents, embeddings
  ├── hathor        → worlds, characters, quests
  └── bellona       → builds, exports, artifacts

// Before
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// After
datasource db {
  provider = "postgresql"
  url      = env("LILITH_DATABASE_URL")
  schemas  = ["lilith"]
}

model Meditation {
  id String @id
  // ...
  @@schema("lilith")
}

model Meditation {
  userId String  // Direct user ID
  user   User    @relation(...)
}

model Meditation {
  authUserId    String  // Reference to oshun_auth.users.id
  lilithProfile LilithProfile @relation(fields: [authUserId], ...)
}

-- Add new column
ALTER TABLE lilith.meditation ADD COLUMN auth_user_id UUID;

-- Migrate data
UPDATE lilith.meditation m
SET auth_user_id = (
  SELECT auth_user_id FROM lilith.profile p WHERE p.id = m.user_id
);

-- Drop old column (after verification)
ALTER TABLE lilith.meditation DROP COLUMN user_id;
ALTER TABLE lilith.meditation RENAME COLUMN auth_user_id TO user_id;

model Entity {
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  deletedAt DateTime?  // Optional soft delete
}

model Entity {
  createdAt DateTime @default(now()) @db.Timestamptz
  updatedAt DateTime @updatedAt @db.Timestamptz
  deletedAt DateTime? @db.Timestamptz
}

{
  "sub": "user-123",
  "email": "user@example.com",
  "tier": "premium",
  "exp": 1704067200
}

{
  "userId": "user-123",
  "organizationId": "org-456",
  "role": "admin",
  "exp": 1704067200
}

{
  "sub": "user-123",
  "email": "user@example.com",
  "iss": "https://auth.oshun.io",
  "aud": ["lilith", "yemaya", "isis"],
  "iat": 1704066300,
  "exp": 1704067200,
  "jti": "token-789",
  "org": "org-456",
  "permissions": ["read:meditations", "write:projects"],
  "roles": ["user", "creator"]
}

# Lilith
lil_live_abc123...
lil_test_xyz789...

# Yemaya
ym_abc123...

# Live keys
sk_live_oshun_abc123...

# Test keys
sk_test_oshun_xyz789...

# Restricted keys (limited scope)
rk_oshun_def456...

# Lilith scopes
meditation:read
meditation:write
user:profile

# Yemaya scopes
projects
assets
export

# Domain-prefixed scopes
lilith:meditation:read
lilith:meditation:write
lilith:user:read

yemaya:projects:read
yemaya:projects:write
yemaya:assets:read
yemaya:assets:write

isis:generation:read
isis:generation:write

# Wildcard scopes
lilith:*        # All Lilith permissions
yemaya:*:read   # Read all Yemaya resources
*               # Full access (admin)

# Core
NODE_ENV=production
LOG_LEVEL=info

# Databases (per domain)
LILITH_DATABASE_URL=postgresql://...?schema=lilith
YEMAYA_DATABASE_URL=postgresql://...?schema=yemaya
ISIS_DATABASE_URL=postgresql://...?schema=isis
# ... etc

# Shared Infrastructure
REDIS_URL=redis://localhost:6379
STORAGE_URL=s3://oshun-assets.s3.us-east-1.amazonaws.com

# Authentication
AUTH_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..."
AUTH_ISSUER=https://auth.oshun.io

# AI Providers (managed by Isis)
ISIS_OPENAI_API_KEY=sk-...
ISIS_ANTHROPIC_API_KEY=sk-ant-...
ISIS_REPLICATE_API_TOKEN=r8_...

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.oshun.io
SENTRY_DSN=https://...@sentry.io/...

# lilith-config.yaml
database:
  host: localhost
  port: 5432

# yemaya.config.json
{
  "storage": {
    "bucket": "yemaya-assets"
  }
}

// config/lilith.config.ts
import { defineConfig } from '@oshun/config';

export default defineConfig({
  domain: 'lilith',
  database: {
    url: process.env.LILITH_DATABASE_URL,
    schema: 'lilith',
  },
  redis: {
    url: process.env.REDIS_URL,
  },
  // Type-safe configuration
});

import { legacyResponseMiddleware } from '@oshun/compat';

// Converts new format to legacy format for old clients
app.use(
  '/api/v1/*',
  legacyResponseMiddleware({
    format: 'lilith', // or 'yemaya'
  })
);

import { EventBridge } from '@oshun/compat';

// Translates old event names to new format
const bridge = new EventBridge({
  mappings: {
    'meditation:completed': 'lilith.meditation.completed',
    project_created: 'yemaya.project.created',
  },
});

await bridge.start();

import { translateApiKey } from '@oshun/compat';

// Converts old format keys to new format
const newKey = translateApiKey('lil_live_abc123');
// Returns: sk_live_oshun_abc123