@mdxui/terminal 2.0.0

package/src/data/saas-collections.ts

@@ -0,0 +1,375 @@
+/**
+ * @mdxui/terminal SaaS Collections
+ *
+ * Pre-built Zod schemas and collections for common SaaS primitives:
+ * - Users: Authentication and user management
+ * - APIKeys: API key management with permissions
+ * - Webhooks: Webhook configuration and event subscriptions
+ * - Teams: Team/organization management with members
+ * - Usage: Usage metrics tracking
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UsersCollection,
+ *   APIKeysCollection,
+ *   WebhooksCollection,
+ *   TeamsCollection,
+ *   UsageCollection,
+ *   type User,
+ *   type APIKey,
+ * } from '@mdxui/terminal'
+ *
+ * // Create collections
+ * const users = UsersCollection()
+ * const apiKeys = APIKeysCollection()
+ *
+ * // Insert data
+ * await users.insert({
+ *   id: 'user-1',
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   role: 'admin',
+ *   createdAt: new Date(),
+ * })
+ *
+ * // Query
+ * const admins = await users.findMany({
+ *   where: { role: 'admin' }
+ * })
+ * ```
+ */
+
+import { z } from 'zod'
+import { createCollection } from './collection'
+import type { Collection } from './types'
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+/**
+ * User role enum - defines access levels
+ */
+export const UserRoleSchema = z.enum(['admin', 'user', 'viewer'])
+
+/**
+ * User schema - validates user account information
+ *
+ * @example
+ * ```typescript
+ * const user = UserSchema.parse({
+ *   id: 'user-1',
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   role: 'admin',
+ *   createdAt: new Date(),
+ * })
+ * ```
+ */
+export const UserSchema = z.object({
+  /** Unique user identifier */
+  id: z.string(),
+  /** User's display name */
+  name: z.string(),
+  /** User's email address (validated format) */
+  email: z.string().email(),
+  /** User's role: admin, user, or viewer */
+  role: UserRoleSchema,
+  /** When the user account was created */
+  createdAt: z.date(),
+})
+
+/**
+ * APIKey schema - validates API key configuration
+ *
+ * @example
+ * ```typescript
+ * const key = APIKeySchema.parse({
+ *   id: 'key-1',
+ *   key: 'sk_test_abc123',
+ *   name: 'Development',
+ *   permissions: ['read:api', 'write:webhooks'],
+ *   expiresAt: new Date('2025-12-31'),
+ * })
+ * ```
+ */
+export const APIKeySchema = z.object({
+  /** Unique key identifier */
+  id: z.string(),
+  /** The actual API key string (secret) */
+  key: z.string(),
+  /** Human-readable name for the key */
+  name: z.string(),
+  /** Array of permission strings this key grants */
+  permissions: z.array(z.string()),
+  /** When the key expires */
+  expiresAt: z.date(),
+})
+
+/**
+ * Webhook schema - validates webhook configuration
+ *
+ * @example
+ * ```typescript
+ * const webhook = WebhookSchema.parse({
+ *   id: 'webhook-1',
+ *   url: 'https://example.com/webhook',
+ *   events: ['user.created', 'user.updated'],
+ *   secret: 'whsec_test_abc123',
+ *   active: true,
+ * })
+ * ```
+ */
+export const WebhookSchema = z.object({
+  /** Unique webhook identifier */
+  id: z.string(),
+  /** Webhook endpoint URL (validated format) */
+  url: z.string().url(),
+  /** Events this webhook listens to (non-empty array) */
+  events: z.array(z.string()).min(1),
+  /** Webhook signing secret */
+  secret: z.string(),
+  /** Whether the webhook is currently active */
+  active: z.boolean(),
+})
+
+/**
+ * Team schema - validates team configuration
+ *
+ * @example
+ * ```typescript
+ * const team = TeamSchema.parse({
+ *   id: 'team-1',
+ *   name: 'Engineering',
+ *   members: ['user-1', 'user-2', 'user-3'],
+ * })
+ * ```
+ */
+export const TeamSchema = z.object({
+  /** Unique team identifier */
+  id: z.string(),
+  /** Team name */
+  name: z.string(),
+  /** Array of user IDs who are members */
+  members: z.array(z.string()),
+})
+
+/**
+ * Usage schema - validates usage metrics
+ *
+ * @example
+ * ```typescript
+ * const usage = UsageSchema.parse({
+ *   id: 'usage-1',
+ *   metric: 'api_calls',
+ *   value: 1500,
+ *   timestamp: new Date(),
+ * })
+ * ```
+ */
+export const UsageSchema = z.object({
+  /** Unique usage record identifier */
+  id: z.string(),
+  /** Name of the metric being tracked */
+  metric: z.string(),
+  /** Numeric value of the metric */
+  value: z.number(),
+  /** When this metric was recorded */
+  timestamp: z.date(),
+})
+
+// ============================================================================
+// Type exports (inferred from schemas)
+// ============================================================================
+
+/** User type - inferred from UserSchema */
+export type User = z.infer<typeof UserSchema>
+
+/** APIKey type - inferred from APIKeySchema */
+export type APIKey = z.infer<typeof APIKeySchema>
+
+/** Webhook type - inferred from WebhookSchema */
+export type Webhook = z.infer<typeof WebhookSchema>
+
+/** Team type - inferred from TeamSchema */
+export type Team = z.infer<typeof TeamSchema>
+
+/** Usage type - inferred from UsageSchema */
+export type Usage = z.infer<typeof UsageSchema>
+
+/** User role type - admin, user, or viewer */
+export type UserRole = z.infer<typeof UserRoleSchema>
+
+// ============================================================================
+// Collection Factory Functions
+// ============================================================================
+
+/**
+ * Creates a Users collection with Zod validation
+ *
+ * @returns A typed Collection<User> for managing user accounts
+ *
+ * @example
+ * ```typescript
+ * const users = UsersCollection()
+ *
+ * // Insert a user
+ * const user = await users.insert({
+ *   id: 'user-1',
+ *   name: 'Alice',
+ *   email: 'alice@example.com',
+ *   role: 'admin',
+ *   createdAt: new Date(),
+ * })
+ *
+ * // Find admins
+ * const admins = await users.findMany({
+ *   where: { role: 'admin' }
+ * })
+ *
+ * // Subscribe to changes
+ * const unsubscribe = users.subscribe((allUsers) => {
+ *   console.log('Users changed:', allUsers.length)
+ * })
+ * ```
+ */
+export function UsersCollection(): Collection<User> {
+  return createCollection<User>({
+    name: 'users',
+    schema: UserSchema,
+    primaryKey: 'id',
+    indexes: ['email', 'role'],
+  })
+}
+
+/**
+ * Creates an APIKeys collection with Zod validation
+ *
+ * @returns A typed Collection<APIKey> for managing API keys
+ *
+ * @example
+ * ```typescript
+ * const apiKeys = APIKeysCollection()
+ *
+ * // Create a new key
+ * const key = await apiKeys.insert({
+ *   id: 'key-1',
+ *   key: 'sk_test_abc123',
+ *   name: 'Development',
+ *   permissions: ['read:api'],
+ *   expiresAt: new Date('2025-12-31'),
+ * })
+ *
+ * // Find non-expired keys
+ * const validKeys = await apiKeys.findMany({
+ *   where: { expiresAt: { $gt: new Date() } }
+ * })
+ * ```
+ */
+export function APIKeysCollection(): Collection<APIKey> {
+  return createCollection<APIKey>({
+    name: 'apiKeys',
+    schema: APIKeySchema,
+    primaryKey: 'id',
+    indexes: ['key', 'name'],
+  })
+}
+
+/**
+ * Creates a Webhooks collection with Zod validation
+ *
+ * @returns A typed Collection<Webhook> for managing webhook configurations
+ *
+ * @example
+ * ```typescript
+ * const webhooks = WebhooksCollection()
+ *
+ * // Create a webhook
+ * await webhooks.insert({
+ *   id: 'webhook-1',
+ *   url: 'https://example.com/webhook',
+ *   events: ['user.created'],
+ *   secret: 'whsec_abc123',
+ *   active: true,
+ * })
+ *
+ * // Find active webhooks
+ * const active = await webhooks.findMany({
+ *   where: { active: true }
+ * })
+ * ```
+ */
+export function WebhooksCollection(): Collection<Webhook> {
+  return createCollection<Webhook>({
+    name: 'webhooks',
+    schema: WebhookSchema,
+    primaryKey: 'id',
+    indexes: ['url', 'active'],
+  })
+}
+
+/**
+ * Creates a Teams collection with Zod validation
+ *
+ * @returns A typed Collection<Team> for managing teams and their members
+ *
+ * @example
+ * ```typescript
+ * const teams = TeamsCollection()
+ *
+ * // Create a team
+ * await teams.insert({
+ *   id: 'team-1',
+ *   name: 'Engineering',
+ *   members: ['user-1', 'user-2'],
+ * })
+ *
+ * // Add a member
+ * await teams.update(
+ *   { id: 'team-1' },
+ *   { members: ['user-1', 'user-2', 'user-3'] }
+ * )
+ * ```
+ */
+export function TeamsCollection(): Collection<Team> {
+  return createCollection<Team>({
+    name: 'teams',
+    schema: TeamSchema,
+    primaryKey: 'id',
+    indexes: ['name'],
+  })
+}
+
+/**
+ * Creates a Usage collection with Zod validation
+ *
+ * @returns A typed Collection<Usage> for tracking usage metrics
+ *
+ * @example
+ * ```typescript
+ * const usage = UsageCollection()
+ *
+ * // Record usage
+ * await usage.insert({
+ *   id: 'usage-1',
+ *   metric: 'api_calls',
+ *   value: 1500,
+ *   timestamp: new Date(),
+ * })
+ *
+ * // Get usage for a specific metric
+ * const apiCalls = await usage.findMany({
+ *   where: { metric: 'api_calls' },
+ *   orderBy: { timestamp: 'desc' }
+ * })
+ * ```
+ */
+export function UsageCollection(): Collection<Usage> {
+  return createCollection<Usage>({
+    name: 'usage',
+    schema: UsageSchema,
+    primaryKey: 'id',
+    indexes: ['metric', 'timestamp'],
+  })
+}