@locusai/shared 0.1.7 → 0.2.2

package/src/models/activity.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { BaseEntitySchema } from "../common";
+import { EventType, SprintStatus, TaskStatus } from "../enums";
+
+export const CommentSchema = BaseEntitySchema.extend({
+  taskId: z.string().uuid(),
+  author: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export type Comment = z.infer<typeof CommentSchema>;
+
+export const ArtifactSchema = BaseEntitySchema.extend({
+  taskId: z.string().uuid(),
+  type: z.string().min(1),
+  title: z.string().min(1),
+  contentText: z.string().optional(),
+  filePath: z.string().optional(),
+  url: z.string().optional(),
+  size: z.string().optional(),
+  createdBy: z.string().min(1),
+});
+
+export type Artifact = z.infer<typeof ArtifactSchema>;
+
+// ============================================================================
+// Event Payloads
+// ============================================================================
+
+export const TaskCreatedPayloadSchema = z.object({
+  title: z.string(),
+});
+
+export const TaskDeletedPayloadSchema = z.object({
+  title: z.string(),
+});
+
+export const StatusChangedPayloadSchema = z.object({
+  title: z.string(),
+  oldStatus: z.nativeEnum(TaskStatus),
+  newStatus: z.nativeEnum(TaskStatus),
+});
+
+export const CommentAddedPayloadSchema = z.object({
+  title: z.string(),
+  author: z.string(),
+  text: z.string(),
+});
+
+export const WorkspaceCreatedPayloadSchema = z.object({
+  name: z.string(),
+});
+
+export const MemberAddedPayloadSchema = z.object({
+  userId: z.string(),
+  role: z.string(),
+});
+
+export const MemberInvitedPayloadSchema = z.object({
+  email: z.string(),
+});
+
+export const SprintCreatedPayloadSchema = z.object({
+  name: z.string(),
+  sprintId: z.string().uuid(),
+});
+
+export const SprintStatusChangedPayloadSchema = z.object({
+  name: z.string(),
+  sprintId: z.string().uuid(),
+  oldStatus: z.nativeEnum(SprintStatus),
+  newStatus: z.nativeEnum(SprintStatus),
+});
+
+export const ChecklistInitializedPayloadSchema = z.object({
+  itemCount: z.number(),
+});
+
+export const CiRanPayloadSchema = z.object({
+  preset: z.string(),
+  ok: z.boolean(),
+  summary: z.string(),
+  source: z.string(),
+  deferred: z.boolean(),
+  processed: z.boolean(),
+  commands: z.array(z.object({ cmd: z.string(), exitCode: z.number() })),
+});
+
+export const EventPayloadSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal(EventType.TASK_CREATED),
+    payload: TaskCreatedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.TASK_DELETED),
+    payload: TaskDeletedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.STATUS_CHANGED),
+    payload: StatusChangedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.COMMENT_ADDED),
+    payload: CommentAddedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.WORKSPACE_CREATED),
+    payload: WorkspaceCreatedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.MEMBER_ADDED),
+    payload: MemberAddedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.MEMBER_INVITED),
+    payload: MemberInvitedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.SPRINT_CREATED),
+    payload: SprintCreatedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.SPRINT_STATUS_CHANGED),
+    payload: SprintStatusChangedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.CHECKLIST_INITIALIZED),
+    payload: ChecklistInitializedPayloadSchema,
+  }),
+  z.object({
+    type: z.literal(EventType.CI_RAN),
+    payload: CiRanPayloadSchema,
+  }),
+]);
+
+export type EventPayload = z.infer<typeof EventPayloadSchema>;
+
+export const EventSchema = z.object({
+  id: z.string(),
+  workspaceId: z.string(),
+  taskId: z.string().uuid().optional().nullable(),
+  userId: z.string().optional().nullable(),
+  type: z.nativeEnum(EventType),
+  payload: z.record(z.string(), z.unknown()),
+  createdAt: z.union([z.date(), z.number()]),
+});
+
+export type Event = z.infer<typeof EventSchema>;
+
+// ============================================================================
+// Parameter & Query Schemas
+// ============================================================================
+
+export const ArtifactParamSchema = z.object({
+  taskId: z.string().uuid("Invalid Task ID"),
+  type: z.string().min(1, "Artifact type required"),
+  filename: z.string().min(1, "Filename required"),
+});
+
+export type ArtifactParam = z.infer<typeof ArtifactParamSchema>;
+
+export const TaskIdOnlyParamSchema = z.object({
+  taskId: z.string().uuid("Invalid Task ID"),
+});
+
+export type TaskIdOnlyParam = z.infer<typeof TaskIdOnlyParamSchema>;
+
+export const EventQuerySchema = z.object({
+  taskId: z.string().uuid("Invalid Task ID").optional(),
+});
+
+export type EventQuery = z.infer<typeof EventQuerySchema>;
+
+export const EventResponseSchema = z.object({
+  event: EventSchema,
+});
+
+export type EventResponse = z.infer<typeof EventResponseSchema>;
+
+export const EventsResponseSchema = z.object({
+  events: z.array(EventSchema),
+});
+
+export type EventsResponse = z.infer<typeof EventsResponseSchema>;
+
+export const ActivityResponseSchema = z.object({
+  activity: z.array(EventSchema),
+});
+
+export type ActivityResponse = z.infer<typeof ActivityResponseSchema>;
+
+export const CommentResponseSchema = z.object({
+  comment: CommentSchema,
+});
+
+export type CommentResponse = z.infer<typeof CommentResponseSchema>;
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+export const ArtifactResponseSchema = z.object({
+  artifact: ArtifactSchema,
+});
+
+export type ArtifactResponse = z.infer<typeof ArtifactResponseSchema>;
+
+export const ArtifactsResponseSchema = z.object({
+  artifacts: z.array(ArtifactSchema),
+});
+
+export type ArtifactsResponse = z.infer<typeof ArtifactsResponseSchema>;
+
+export const CreateArtifactSchema = z.object({
+  taskId: z.string().uuid(),
+  type: z.string().min(1),
+  title: z.string().min(1),
+  contentText: z.string().optional(),
+});
+
+export type CreateArtifact = z.infer<typeof CreateArtifactSchema>;
+
+export const ReportCiResultSchema = z.object({
+  workspaceId: z.string().uuid(),
+  taskId: z.string().uuid().optional(),
+  preset: z.string(),
+  ok: z.boolean(),
+  summary: z.string(),
+  commands: z.array(
+    z.object({
+      cmd: z.string(),
+      exitCode: z.number(),
+    })
+  ),
+});
+
+export type ReportCiResult = z.infer<typeof ReportCiResultSchema>;

package/src/models/agent.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const LockSchema = z.object({
+  agentId: z.string().min(1),
+  ttlSeconds: z.number().positive(),
+});
+
+export const UnlockSchema = z.object({
+  agentId: z.string().min(1),
+});
+
+export type Lock = z.infer<typeof LockSchema>;
+export type Unlock = z.infer<typeof UnlockSchema>;

package/src/models/auth.ts

@@ -0,0 +1,188 @@
+/**
+ * Authentication Models and Schemas
+ */
+
+import { z } from "zod";
+import { UserRole } from "../enums";
+import { UserSchema } from "./user";
+
+// ============================================================================
+// Authenticated User Types (for request context)
+// ============================================================================
+
+/**
+ * User authenticated via JWT (web dashboard)
+ */
+export const JwtAuthUserSchema = z.object({
+  authType: z.literal("jwt"),
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  role: z.nativeEnum(UserRole),
+  orgId: z.string().uuid().nullable().optional(),
+  workspaceId: z.string().uuid().nullable().optional(),
+});
+
+export type JwtAuthUser = z.infer<typeof JwtAuthUserSchema>;
+
+/**
+ * User authenticated via API Key (CLI/agents)
+ * Note: API keys don't have a real user ID - they represent organization-level access
+ */
+export const ApiKeyAuthUserSchema = z.object({
+  authType: z.literal("api_key"),
+  apiKeyId: z.string().uuid(),
+  apiKeyName: z.string(),
+  orgId: z.string().uuid(),
+});
+
+export type ApiKeyAuthUser = z.infer<typeof ApiKeyAuthUserSchema>;
+
+/**
+ * Union type for any authenticated request
+ */
+export const AuthenticatedUserSchema = z.discriminatedUnion("authType", [
+  JwtAuthUserSchema,
+  ApiKeyAuthUserSchema,
+]);
+
+export type AuthenticatedUser = z.infer<typeof AuthenticatedUserSchema>;
+
+/**
+ * Type guard to check if user is JWT authenticated
+ */
+export function isJwtUser(user: AuthenticatedUser): user is JwtAuthUser {
+  return user.authType === "jwt";
+}
+
+/**
+ * Type guard to check if user is API key authenticated
+ */
+export function isApiKeyUser(user: AuthenticatedUser): user is ApiKeyAuthUser {
+  return user.authType === "api_key";
+}
+
+/**
+ * Get the user ID for event logging. Returns null for API key users.
+ * Use this when you need to store a reference to the user in the database.
+ */
+export function getAuthUserId(user: AuthenticatedUser): string | null {
+  return isJwtUser(user) ? user.id : null;
+}
+
+// ============================================================================
+// Auth Responses
+// ============================================================================
+
+export const AuthResponseSchema = z.object({
+  token: z.string(),
+  user: UserSchema,
+});
+
+export type AuthResponse = z.infer<typeof AuthResponseSchema>;
+export type LoginResponse = AuthResponse;
+
+// ============================================================================
+// OTP-Based Auth (Cloud)
+// ============================================================================
+
+export const OtpRequestSchema = z.object({
+  email: z.string().email("Invalid email address"),
+});
+
+export type OtpRequest = z.infer<typeof OtpRequestSchema>;
+
+export const VerifyOtpSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  otp: z.string().length(6, "Verification code must be 6 digits"),
+});
+
+export type VerifyOtp = z.infer<typeof VerifyOtpSchema>;
+
+export const CompleteRegistrationSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  otp: z.string().length(6, "Verification code must be 6 digits"),
+  name: z.string().min(1, "Name is required").max(100),
+  companyName: z.string().max(100).optional(),
+  teamSize: z.enum(["solo", "2-10", "11-50", "51-200", "200+"]).optional(),
+  userRole: z
+    .enum(["developer", "designer", "product_manager", "other"])
+    .optional(),
+  workspaceName: z.string().max(100).optional(),
+  invitedEmails: z.array(z.string().email()).optional(),
+});
+
+export type CompleteRegistration = z.infer<typeof CompleteRegistrationSchema>;
+
+// ============================================================================
+// Internal Context & API Keys
+// ============================================================================
+
+export const JWTPayloadSchema = z.object({
+  sub: z.string(), // User ID
+  email: z.string().email(),
+  name: z.string(),
+  role: z.string(),
+  orgId: z.string().uuid().optional(),
+  iat: z.number(),
+  exp: z.number(),
+});
+
+export type JWTPayload = z.infer<typeof JWTPayloadSchema>;
+
+export const AuthContextSchema = z.object({
+  userId: z.string(),
+  email: z.string().email(),
+  name: z.string(),
+  role: z.string(),
+  orgId: z.string().uuid().optional(),
+  workspaceId: z.string().uuid().optional(),
+  authType: z.enum(["jwt", "api_key", "local"]),
+});
+
+export type AuthContext = z.infer<typeof AuthContextSchema>;
+
+export const APIKeySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  keyPrefix: z.string(),
+  workspaceId: z.string(),
+  lastUsedAt: z.number().nullable(),
+  createdAt: z.number(),
+});
+
+export type APIKey = z.infer<typeof APIKeySchema>;
+
+export const APIKeyCreateResponseSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  keyPrefix: z.string(),
+  key: z.string(),
+  createdAt: z.number(),
+});
+
+export type APIKeyCreateResponse = z.infer<typeof APIKeyCreateResponseSchema>;
+
+// ============================================================================
+// Parameter & Query Schemas
+// ============================================================================
+
+export const ApiKeyIdParamSchema = z.object({
+  id: z.string().uuid("Invalid API Key ID"),
+});
+
+export type ApiKeyIdParam = z.infer<typeof ApiKeyIdParamSchema>;
+
+export const ApiKeyQuerySchema = z.object({
+  workspaceId: z.string().uuid("Invalid Workspace ID").optional(),
+});
+
+export type ApiKeyQuery = z.infer<typeof ApiKeyQuerySchema>;
+
+export const CreateApiKeySchema = z.object({
+  workspaceId: z.string().uuid("Invalid Workspace ID").optional(),
+  name: z.string().min(1, "Name is required").max(100),
+  expiresInDays: z.number().int().positive().optional(),
+});
+
+export type CreateApiKey = z.infer<typeof CreateApiKeySchema>;

package/src/models/ci.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const RecordCiSchema = z.object({
+  taskId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  result: z.object({
+    ok: z.boolean(),
+    summary: z.string(),
+    commands: z.array(
+      z.object({
+        cmd: z.string(),
+        exitCode: z.number(),
+        durationMs: z.number().optional(),
+        error: z.string().optional(),
+      })
+    ),
+    preset: z.string(),
+  }),
+});
+
+export type RecordCi = z.infer<typeof RecordCiSchema>;

package/src/models/doc-group.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { BaseEntitySchema } from "../common";
+
+export const DocGroupSchema = BaseEntitySchema.extend({
+  workspaceId: z.string().uuid(),
+  name: z.string().min(1, "Name is required"),
+  order: z.number().default(0),
+});
+
+export type DocGroup = z.infer<typeof DocGroupSchema>;
+
+export const CreateDocGroupSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  order: z.number().optional(),
+});
+
+export type CreateDocGroup = z.infer<typeof CreateDocGroupSchema>;
+
+export const UpdateDocGroupSchema = z.object({
+  name: z.string().min(1).optional(),
+  order: z.number().optional(),
+});
+
+export type UpdateDocGroup = z.infer<typeof UpdateDocGroupSchema>;
+
+export const DocGroupResponseSchema = z.object({
+  group: DocGroupSchema,
+});
+
+export type DocGroupResponse = z.infer<typeof DocGroupResponseSchema>;
+
+export const DocGroupsResponseSchema = z.object({
+  groups: z.array(DocGroupSchema),
+});
+
+export type DocGroupsResponse = z.infer<typeof DocGroupsResponseSchema>;
+
+export const DocGroupIdParamSchema = z.object({
+  id: z.string().uuid("Invalid Group ID"),
+});
+
+export type DocGroupIdParam = z.infer<typeof DocGroupIdParamSchema>;

package/src/models/doc.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { BaseEntitySchema } from "../common";
+
+// Forward declaration for circular reference
+export const DocGroupSchemaForDoc = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+});
+
+export const DocSchema = BaseEntitySchema.extend({
+  workspaceId: z.string().uuid(),
+  groupId: z.string().uuid().nullable().optional(),
+  title: z.string().min(1, "Title is required"),
+  content: z.string().default(""),
+  group: DocGroupSchemaForDoc.nullable().optional(),
+});
+
+export type Doc = z.infer<typeof DocSchema>;
+
+export const CreateDocSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  content: z.string().optional(),
+  groupId: z.string().uuid().optional(),
+});
+
+export type CreateDoc = z.infer<typeof CreateDocSchema>;
+
+export const UpdateDocSchema = z.object({
+  title: z.string().min(1).optional(),
+  content: z.string().optional(),
+  groupId: z.string().uuid().nullable().optional(),
+});
+
+export type UpdateDoc = z.infer<typeof UpdateDocSchema>;
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+export const DocResponseSchema = z.object({
+  doc: DocSchema,
+});
+
+export type DocResponse = z.infer<typeof DocResponseSchema>;
+
+export const DocsResponseSchema = z.object({
+  docs: z.array(DocSchema),
+});
+
+export type DocsResponse = z.infer<typeof DocsResponseSchema>;
+
+// ============================================================================
+// Parameter & Query Schemas
+// ============================================================================
+
+export const DocIdParamSchema = z.object({
+  id: z.string().uuid("Invalid Doc ID"),
+});
+
+export type DocIdParam = z.infer<typeof DocIdParamSchema>;
+
+export const DocQuerySchema = z.object({
+  workspaceId: z.string().uuid("Invalid Workspace ID").optional(),
+});
+
+export type DocQuery = z.infer<typeof DocQuerySchema>;

package/src/models/index.ts

@@ -0,0 +1,12 @@
+export * from "./activity";
+export * from "./agent";
+export * from "./auth";
+export * from "./ci";
+export * from "./doc";
+export * from "./doc-group";
+export * from "./invitation";
+export * from "./organization";
+export * from "./sprint";
+export * from "./task";
+export * from "./user";
+export * from "./workspace";

package/src/models/invitation.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { BaseEntitySchema } from "../common";
+import { MembershipRole } from "../enums";
+
+export const InvitationSchema = BaseEntitySchema.extend({
+  orgId: z.string().uuid("Invalid Organization ID"),
+  email: z.string().email("Invalid email address"),
+  role: z.nativeEnum(MembershipRole),
+  token: z.string(),
+  expiresAt: z.number(),
+  acceptedAt: z.number().nullable().optional(),
+  invitedBy: z.string().uuid(),
+});
+
+export type Invitation = z.infer<typeof InvitationSchema>;
+
+export const CreateInvitationSchema = z.object({
+  orgId: z.string().uuid("Invalid Organization ID"),
+  email: z.string().email("Invalid email address"),
+  role: z.nativeEnum(MembershipRole).default(MembershipRole.MEMBER),
+});
+
+export type CreateInvitation = z.infer<typeof CreateInvitationSchema>;
+
+export const AcceptInvitationSchema = z.object({
+  token: z.string().min(1, "Invitation token is required"),
+  name: z.string().min(1, "Name is required").optional(),
+});
+
+export type AcceptInvitation = z.infer<typeof AcceptInvitationSchema>;
+
+// ============================================================================
+// Parameter & Query Schemas
+// ============================================================================
+
+export const InvitationIdParamSchema = z.object({
+  id: z.string().uuid("Invalid Invitation ID"),
+});
+
+export type InvitationIdParam = z.infer<typeof InvitationIdParamSchema>;
+
+export const InvitationVerifyParamSchema = z.object({
+  token: z.string().min(1, "Token required"),
+});
+
+export type InvitationVerifyParam = z.infer<typeof InvitationVerifyParamSchema>;
+
+export const InvitationQuerySchema = z.object({
+  orgId: z.string().uuid("Invalid Organization ID").optional(),
+});
+
+export type InvitationQuery = z.infer<typeof InvitationQuerySchema>;
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+export const InvitationResponseSchema = z.object({
+  invitation: InvitationSchema,
+  userExists: z.boolean().optional(),
+});
+
+export type InvitationResponse = z.infer<typeof InvitationResponseSchema>;
+
+export const InvitationsResponseSchema = z.object({
+  invitations: z.array(InvitationSchema),
+});
+
+export type InvitationsResponse = z.infer<typeof InvitationsResponseSchema>;
+
+export const AcceptInvitationResponseSchema = z.object({
+  membership: z.object({
+    id: z.string().uuid(),
+    userId: z.string().uuid(),
+    orgId: z.string().uuid(),
+    role: z.nativeEnum(MembershipRole),
+    createdAt: z.number(),
+  }),
+});
+
+export type AcceptInvitationResponse = z.infer<
+  typeof AcceptInvitationResponseSchema
+>;