@useatlas/types 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Sywulak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @useatlas/types
+
+Shared TypeScript types for the [Atlas](https://useatlas.dev) text-to-SQL agent.
+
+## Install
+
+```bash
+bun add @useatlas/types
+```
+
+## Usage
+
+Import from the barrel or use deep imports for tree-shaking:
+
+```typescript
+import type { Conversation, AuthMode, DBType } from "@useatlas/types";
+
+// Deep imports
+import type { ChatErrorCode } from "@useatlas/types/errors";
+import type { Recipient } from "@useatlas/types/scheduled-task";
+import { parseChatError, authErrorMessage } from "@useatlas/types/errors";
+```
+
+## Modules
+
+| Import path | Contents |
+|-------------|----------|
+| `@useatlas/types` | Barrel — re-exports everything below |
+| `@useatlas/types/auth` | `AuthMode`, `AtlasRole`, `AtlasUser` |
+| `@useatlas/types/conversation` | `Conversation`, `Message`, `ConversationWithMessages` |
+| `@useatlas/types/connection` | `DBType`, `ConnectionHealth`, `ConnectionInfo`, `ConnectionDetail` |
+| `@useatlas/types/action` | `ActionApprovalMode`, `ActionDisplayStatus`, `ActionToolResultShape` |
+| `@useatlas/types/scheduled-task` | `ScheduledTask`, `Recipient`, `ScheduledTaskRun` |
+| `@useatlas/types/errors` | `ChatErrorCode`, `ChatErrorInfo`, `parseChatError`, `authErrorMessage` |
+| `@useatlas/types/semantic` | `Dimension`, `SemanticEntitySummary`, `SemanticEntityDetail` |
+| `@useatlas/types/share` | `ShareLink` |
+
+## License
+
+MIT

package/dist/abuse.d.ts

@@ -0,0 +1,42 @@
+/** Graduated abuse response levels (escalation order). */
+export declare const ABUSE_LEVELS: readonly ["none", "warning", "throttled", "suspended"];
+export type AbuseLevel = (typeof ABUSE_LEVELS)[number];
+/** Which anomaly detector triggered the abuse event. */
+export declare const ABUSE_TRIGGERS: readonly ["query_rate", "error_rate", "unique_tables", "manual"];
+export type AbuseTrigger = (typeof ABUSE_TRIGGERS)[number];
+/** A single abuse event recorded in the audit trail. */
+export interface AbuseEvent {
+    id: string;
+    workspaceId: string;
+    level: AbuseLevel;
+    trigger: AbuseTrigger;
+    message: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    /** Who initiated the event — "system" for auto-detection, user ID for manual reinstate. */
+    actor: string;
+}
+/** Current abuse status for a workspace. */
+export interface AbuseStatus {
+    workspaceId: string;
+    workspaceName: string | null;
+    level: AbuseLevel;
+    trigger: AbuseTrigger | null;
+    message: string | null;
+    updatedAt: string;
+    /** Recent abuse events for this workspace. */
+    events: AbuseEvent[];
+}
+/** Abuse threshold configuration (read-only from admin API). */
+export interface AbuseThresholdConfig {
+    /** Max queries per workspace per sliding window. */
+    queryRateLimit: number;
+    /** Sliding window duration in seconds. */
+    queryRateWindowSeconds: number;
+    /** Max error rate (0–1) before escalation. */
+    errorRateThreshold: number;
+    /** Max unique tables accessed per window before escalation. */
+    uniqueTablesLimit: number;
+    /** Delay injected for throttled workspaces, in milliseconds. */
+    throttleDelayMs: number;
+}

package/dist/action.d.ts

@@ -1,29 +1,83 @@
+import type { AuthMode } from "./auth";
 export declare const ACTION_APPROVAL_MODES: readonly ["auto", "manual", "admin-only"];
 export type ActionApprovalMode = (typeof ACTION_APPROVAL_MODES)[number];
-/** Status lifecycle for action tools that require user approval. */
-export type ActionStatus = "pending_approval" | "approved" | "executed" | "auto_approved" | "denied" | "failed" | "rolled_back" | "timed_out";
-/** A status that is terminal (no longer pending). */
-export type ResolvedStatus = Exclude<ActionStatus, "pending_approval">;
-/** Single source of truth for every ActionStatus value. */
+/**
+ * Display status lifecycle for action tools that require user approval.
+ *
+ * Distinct from the server-internal `ActionStatus` which uses "pending"
+ * instead of "pending_approval".
+ */
+export type ActionDisplayStatus = "pending_approval" | "approved" | "executed" | "auto_approved" | "denied" | "failed" | "rolled_back" | "timed_out";
+/** A display status that is terminal (no longer pending). */
+export type ResolvedDisplayStatus = Exclude<ActionDisplayStatus, "pending_approval">;
+/** Single source of truth for every ActionDisplayStatus value. */
 export declare const ALL_STATUSES: readonly ["pending_approval", "approved", "executed", "auto_approved", "denied", "failed", "rolled_back", "timed_out"];
 /** All statuses that are terminal (no longer pending). */
-export declare const RESOLVED_STATUSES: ReadonlySet<ActionStatus>;
-/** Shape returned by action tools in the tool result. */
-export interface ActionToolResultShape {
-    status: ActionStatus;
+export declare const RESOLVED_STATUSES: ReadonlySet<ActionDisplayStatus>;
+/** Discriminated union returned by action tools in the tool result. */
+export type ActionToolResultShape = {
+    status: "pending_approval";
+    actionId: string;
+    summary: string;
+    details?: Record<string, unknown>;
+} | {
+    status: "approved" | "executed" | "auto_approved";
     actionId: string;
+    result: unknown;
     summary?: string;
     details?: Record<string, unknown>;
-    result?: unknown;
+} | {
+    status: "denied";
+    actionId: string;
     reason?: string;
-    error?: string;
-}
+    summary?: string;
+    details?: Record<string, unknown>;
+} | {
+    status: "failed";
+    actionId: string;
+    error: string;
+    summary?: string;
+    details?: Record<string, unknown>;
+} | {
+    status: "rolled_back" | "timed_out";
+    actionId: string;
+    summary?: string;
+    details?: Record<string, unknown>;
+};
 /** API response when approving or denying an action. */
 export interface ActionApprovalResponse {
     actionId: string;
-    status: ActionStatus;
+    status: ActionDisplayStatus;
     result?: unknown;
     error?: string;
 }
+export declare const ACTION_STATUSES: readonly ["pending", "approved", "denied", "executed", "failed", "timed_out", "auto_approved", "rolled_back"];
+export type ActionStatus = (typeof ACTION_STATUSES)[number];
+/** Information needed to undo an executed action. */
+export interface RollbackInfo {
+    method: string;
+    params: Record<string, unknown>;
+}
+/** Database row shape for the action_log table. */
+export interface ActionLogEntry {
+    id: string;
+    requested_at: string;
+    resolved_at: string | null;
+    executed_at: string | null;
+    requested_by: string | null;
+    /** Stores the approver for approved actions and the denier for denied actions. */
+    approved_by: string | null;
+    auth_mode: AuthMode;
+    action_type: string;
+    target: string;
+    summary: string;
+    payload: Record<string, unknown>;
+    status: ActionStatus;
+    result: unknown;
+    error: string | null;
+    rollback_info: RollbackInfo | null;
+    conversation_id: string | null;
+    request_id: string | null;
+}
 /** Type guard: returns true if `result` looks like an action tool result. */
 export declare function isActionToolResult(result: unknown): result is ActionToolResultShape;

package/dist/action.js

@@ -11,16 +11,48 @@ var ALL_STATUSES = [
   "timed_out"
 ];
 var RESOLVED_STATUSES = new Set(ALL_STATUSES.filter((s) => s !== "pending_approval"));
+var ACTION_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "executed",
+  "failed",
+  "timed_out",
+  "auto_approved",
+  "rolled_back"
+];
 var VALID_STATUSES = new Set(ALL_STATUSES);
 function isActionToolResult(result) {
   if (result == null || typeof result !== "object")
     return false;
   const r = result;
-  return typeof r.actionId === "string" && typeof r.status === "string" && VALID_STATUSES.has(r.status);
+  if (typeof r.actionId !== "string" || r.actionId.length === 0)
+    return false;
+  if (typeof r.status !== "string")
+    return false;
+  if (!VALID_STATUSES.has(r.status))
+    return false;
+  switch (r.status) {
+    case "pending_approval":
+      return typeof r.summary === "string";
+    case "approved":
+    case "executed":
+    case "auto_approved":
+      return "result" in r;
+    case "failed":
+      return typeof r.error === "string";
+    case "denied":
+    case "rolled_back":
+    case "timed_out":
+      return true;
+    default:
+      return false;
+  }
 }
 export {
   isActionToolResult,
   RESOLVED_STATUSES,
   ALL_STATUSES,
+  ACTION_STATUSES,
   ACTION_APPROVAL_MODES
 };

package/dist/approval.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Approval workflow types shared across API, frontend, and SDK.
+ *
+ * Enterprise customers can configure approval rules that intercept sensitive
+ * queries (by table, column, or cost threshold) and require sign-off before
+ * execution.
+ */
+export declare const APPROVAL_RULE_TYPES: readonly ["table", "column", "cost"];
+export type ApprovalRuleType = (typeof APPROVAL_RULE_TYPES)[number];
+export declare const APPROVAL_STATUSES: readonly ["pending", "approved", "denied", "expired"];
+export type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
+export interface ApprovalRule {
+    id: string;
+    orgId: string;
+    name: string;
+    ruleType: ApprovalRuleType;
+    /** For table rules: table name pattern. For column rules: column name pattern. For cost: unused. */
+    pattern: string;
+    /** For cost rules: threshold value. Null for table/column rules. */
+    threshold: number | null;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ApprovalRequest {
+    id: string;
+    orgId: string;
+    ruleId: string;
+    ruleName: string;
+    requesterId: string;
+    requesterEmail: string | null;
+    /** The SQL query awaiting approval. */
+    querySql: string;
+    explanation: string | null;
+    connectionId: string;
+    tablesAccessed: string[];
+    columnsAccessed: string[];
+    status: ApprovalStatus;
+    reviewerId: string | null;
+    reviewerEmail: string | null;
+    reviewComment: string | null;
+    reviewedAt: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface CreateApprovalRuleRequest {
+    name: string;
+    ruleType: ApprovalRuleType;
+    pattern: string;
+    threshold?: number | null;
+    enabled?: boolean;
+}
+export interface UpdateApprovalRuleRequest {
+    name?: string;
+    pattern?: string;
+    threshold?: number | null;
+    enabled?: boolean;
+}
+export interface ReviewApprovalRequest {
+    action: "approve" | "deny";
+    comment?: string;
+}

package/dist/auth.d.ts

@@ -7,7 +7,7 @@
  */
 export declare const AUTH_MODES: readonly ["none", "simple-key", "managed", "byot"];
 export type AuthMode = (typeof AUTH_MODES)[number];
-export declare const ATLAS_ROLES: readonly ["viewer", "analyst", "admin"];
+export declare const ATLAS_ROLES: readonly ["member", "admin", "owner", "platform_admin"];
 export type AtlasRole = (typeof ATLAS_ROLES)[number];
 export interface AtlasUser {
     id: string;
@@ -15,6 +15,8 @@ export interface AtlasUser {
     label: string;
     /** Permission role for action approval. Defaults based on auth mode when not set. */
     role?: AtlasRole;
+    /** Active organization ID from session. All data is scoped to this org. */
+    activeOrganizationId?: string;
     /** Auth-source claims for RLS policy evaluation (JWT payload, session user, or env-derived). */
     claims?: Readonly<Record<string, unknown>>;
 }

package/dist/auth.js

@@ -1,6 +1,6 @@
 // src/auth.ts
 var AUTH_MODES = ["none", "simple-key", "managed", "byot"];
-var ATLAS_ROLES = ["viewer", "analyst", "admin"];
+var ATLAS_ROLES = ["member", "admin", "owner", "platform_admin"];
 export {
   AUTH_MODES,
   ATLAS_ROLES

package/dist/backups.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Backup and disaster recovery types.
+ *
+ * Used by the platform admin console for managing automated
+ * backups of the internal PostgreSQL database.
+ */
+export declare const BACKUP_STATUSES: readonly ["in_progress", "completed", "failed", "verified"];
+export type BackupStatus = (typeof BACKUP_STATUSES)[number];
+export interface BackupEntry {
+    id: string;
+    createdAt: string;
+    /** Compressed backup size in bytes. Null while in_progress. */
+    sizeBytes: number | null;
+    status: BackupStatus;
+    /** Filesystem or S3 path where the backup is stored. */
+    storagePath: string;
+    /** When this backup will be auto-purged based on retention policy. */
+    retentionExpiresAt: string;
+    /** Error message if status is "failed". */
+    errorMessage: string | null;
+}
+export interface BackupConfig {
+    /** Cron expression for automated backups. Default: "0 3 * * *" (daily 03:00 UTC). */
+    schedule: string;
+    /** Number of days to retain backups before auto-purge. Default: 30. */
+    retentionDays: number;
+    /** Directory or S3 URI for backup storage. */
+    storagePath: string;
+}

package/dist/billing.d.ts

@@ -0,0 +1,20 @@
+/** Overage status levels for a workspace's usage against its plan limits. */
+export type OverageStatus = "ok" | "warning" | "soft_limit" | "hard_limit";
+/**
+ * Usage status for a single metered dimension (queries or tokens).
+ *
+ * Included in billing API responses and enforcement headers so clients
+ * can display usage bars, warnings, and upgrade CTAs.
+ */
+export interface PlanLimitStatus {
+    /** Which metric this status applies to. */
+    metric: "queries" | "tokens";
+    /** Current usage count for the billing period. */
+    currentUsage: number;
+    /** Plan limit for the billing period. -1 = unlimited. */
+    limit: number;
+    /** Usage as a percentage of the limit. 0 = no usage, 100 = at limit. No upper bound. */
+    usagePercent: number;
+    /** Overage status level. */
+    status: OverageStatus;
+}

package/dist/branding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Workspace branding (white-labeling) types shared across API, frontend, and SDK.
+ *
+ * Enterprise customers can configure custom logo, colors, favicon, and hide
+ * Atlas branding per workspace.
+ */
+export interface WorkspaceBranding {
+    id: string;
+    orgId: string;
+    logoUrl: string | null;
+    logoText: string | null;
+    /** 6-digit hex color (e.g. #FF5500), or null for Atlas default. */
+    primaryColor: string | null;
+    faviconUrl: string | null;
+    hideAtlasBranding: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Public-safe subset of WorkspaceBranding (no internal IDs or timestamps).
+ * Returned by the public GET /api/v1/branding endpoint.
+ */
+export type WorkspaceBrandingPublic = Pick<WorkspaceBranding, "logoUrl" | "logoText" | "primaryColor" | "faviconUrl" | "hideAtlasBranding">;
+/**
+ * Input for setting workspace branding. This is a full replacement —
+ * any field not included is reset to null (or false for hideAtlasBranding).
+ * Callers must send all fields to preserve existing values.
+ */
+export interface SetWorkspaceBrandingInput {
+    logoUrl?: string | null;
+    logoText?: string | null;
+    /** 6-digit hex color (e.g. #FF5500). Set to null to clear. */
+    primaryColor?: string | null;
+    faviconUrl?: string | null;
+    hideAtlasBranding?: boolean;
+}

package/dist/compliance.d.ts

@@ -0,0 +1,110 @@
+/**
+ * PII detection and column masking types shared across API, frontend, and SDK.
+ *
+ * Enterprise customers can enable PII detection during database profiling to
+ * auto-tag sensitive columns. Masking rules control how PII-tagged columns
+ * appear in query results based on user role.
+ */
+export declare const PII_CATEGORIES: readonly ["email", "phone", "ssn", "credit_card", "name", "ip_address", "date_of_birth", "address", "passport", "driver_license", "other"];
+export type PIICategory = (typeof PII_CATEGORIES)[number];
+export declare const PII_CONFIDENCE_LEVELS: readonly ["high", "medium", "low"];
+export type PIIConfidence = (typeof PII_CONFIDENCE_LEVELS)[number];
+export declare const MASKING_STRATEGIES: readonly ["full", "partial", "hash", "redact"];
+export type MaskingStrategy = (typeof MASKING_STRATEGIES)[number];
+export declare const PII_DETECTION_METHODS: readonly ["regex", "column_name", "type_heuristic"];
+export type PIIDetectionMethod = (typeof PII_DETECTION_METHODS)[number];
+export interface PIIDetection {
+    /** The detected PII category. */
+    category: PIICategory;
+    /** Confidence level of the detection. */
+    confidence: PIIConfidence;
+    /** How the detection was made. */
+    method: PIIDetectionMethod;
+    /** Human-readable reason for the detection. */
+    reason: string;
+}
+/** Roles relevant to masking decisions. */
+export declare const MASKING_ROLES: readonly ["admin", "owner", "analyst", "viewer", "member"];
+export type MaskingRole = (typeof MASKING_ROLES)[number];
+export interface PIIColumnClassification {
+    id: string;
+    orgId: string;
+    /** Entity table name. */
+    tableName: string;
+    /** Column name within the table. */
+    columnName: string;
+    /** Connection ID for the datasource. */
+    connectionId: string;
+    /** Detected or manually assigned PII category. */
+    category: PIICategory;
+    /** Detection confidence level. */
+    confidence: PIIConfidence;
+    /** Masking strategy to apply in query results. */
+    maskingStrategy: MaskingStrategy;
+    /** Whether this detection has been reviewed by an admin. */
+    reviewed: boolean;
+    /** If true, admin dismissed this as a false positive. */
+    dismissed: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UpdatePIIClassificationRequest {
+    category?: PIICategory;
+    maskingStrategy?: MaskingStrategy;
+    dismissed?: boolean;
+    reviewed?: boolean;
+}
+export declare const COMPLIANCE_REPORT_TYPES: readonly ["data-access", "user-activity"];
+export type ComplianceReportType = (typeof COMPLIANCE_REPORT_TYPES)[number];
+export declare const COMPLIANCE_EXPORT_FORMATS: readonly ["json", "csv"];
+export type ComplianceExportFormat = (typeof COMPLIANCE_EXPORT_FORMATS)[number];
+export interface ComplianceReportFilters {
+    startDate: string;
+    endDate: string;
+    userId?: string;
+    role?: string;
+    table?: string;
+}
+/** A single row in the data access report. */
+export interface DataAccessRow {
+    tableName: string;
+    userId: string;
+    userEmail: string | null;
+    userRole: string | null;
+    queryCount: number;
+    uniqueColumns: string[];
+    hasPII: boolean;
+    firstAccess: string;
+    lastAccess: string;
+}
+export interface DataAccessReport {
+    rows: DataAccessRow[];
+    summary: {
+        totalQueries: number;
+        uniqueUsers: number;
+        uniqueTables: number;
+        piiTablesAccessed: number;
+    };
+    filters: ComplianceReportFilters;
+    generatedAt: string;
+}
+/** A single row in the user activity report. */
+export interface UserActivityRow {
+    userId: string;
+    userEmail: string | null;
+    role: string | null;
+    totalQueries: number;
+    tablesAccessed: string[];
+    lastActiveAt: string | null;
+    lastLoginAt: string | null;
+}
+export interface UserActivityReport {
+    rows: UserActivityRow[];
+    summary: {
+        totalUsers: number;
+        activeUsers: number;
+        totalQueries: number;
+    };
+    filters: ComplianceReportFilters;
+    generatedAt: string;
+}

package/dist/connection.d.ts

@@ -36,6 +36,36 @@ export interface ConnectionInfo {
     description?: string | null;
     health?: ConnectionHealth;
 }
+/** Real-time pool size counters (only available for core adapters with pool access). */
+export interface PoolStats {
+    totalSize: number;
+    activeCount: number;
+    idleCount: number;
+    waitingCount: number;
+}
+/** Wire format for per-connection pool metrics. */
+export interface PoolMetrics {
+    connectionId: string;
+    dbType: string;
+    pool: PoolStats | null;
+    totalQueries: number;
+    totalErrors: number;
+    avgQueryTimeMs: number;
+    consecutiveFailures: number;
+    lastDrainAt: string | null;
+}
+/** Wire format for per-org pool metrics (extends PoolMetrics with org scope). */
+export interface OrgPoolMetrics extends PoolMetrics {
+    orgId: string;
+}
+/** Wire format for org pool configuration (returned by admin API). */
+export interface OrgPoolConfig {
+    maxConnections: number;
+    idleTimeoutMs: number;
+    maxOrgs: number;
+    warmupProbes: number;
+    drainThreshold: number;
+}
 /** Wire format for a single connection detail response. */
 export interface ConnectionDetail {
     id: string;

package/dist/conversation.d.ts

@@ -10,6 +10,34 @@ export interface Conversation {
     starred: boolean;
     createdAt: string;
     updatedAt: string;
+    notebookState?: NotebookStateWire | null;
+}
+/** Server-persisted notebook state stored as JSONB on the conversation. */
+export interface NotebookStateWire {
+    version: number;
+    /** Custom display order of cell IDs (empty = natural message order). */
+    cellOrder?: string[];
+    /** Per-cell persisted properties (only collapsed; editing/status are transient). */
+    cellProps?: Record<string, {
+        collapsed?: boolean;
+    }>;
+    /** Fork branches originating from this conversation (stored on root only). */
+    branches?: ForkBranchWire[];
+    /** If this conversation is a fork, the root conversation ID. */
+    forkRootId?: string;
+    /** If this conversation is a fork, the cell ID at the fork point. */
+    forkPointCellId?: string;
+    /** Text cell content keyed by cell ID (text cells are not message-backed). */
+    textCells?: Record<string, {
+        content: string;
+    }>;
+}
+/** A fork branch — metadata for a forked conversation. */
+export interface ForkBranchWire {
+    conversationId: string;
+    forkPointCellId: string;
+    label: string;
+    createdAt: string;
 }
 export interface Message {
     id: string;

package/dist/domain.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom domain types for enterprise workspace branding.
+ *
+ * Workspaces can register custom domains (e.g. data.customer.com)
+ * that are provisioned via Railway's custom domain API. Railway
+ * handles TLS certificates (Let's Encrypt) automatically. Atlas
+ * stores the mapping from domain to workspace for host-based routing.
+ */
+export declare const DOMAIN_STATUSES: readonly ["pending", "verified", "failed"];
+export type DomainStatus = (typeof DOMAIN_STATUSES)[number];
+export declare const CERTIFICATE_STATUSES: readonly ["PENDING", "ISSUED", "FAILED"];
+export type CertificateStatus = (typeof CERTIFICATE_STATUSES)[number];
+export interface CustomDomain {
+    id: string;
+    workspaceId: string;
+    domain: string;
+    status: DomainStatus;
+    /** Railway domain ID — used for Railway API calls. */
+    railwayDomainId: string | null;
+    /** CNAME target from Railway (e.g. abc123.up.railway.app). */
+    cnameTarget: string | null;
+    /** Current certificate status from Railway. */
+    certificateStatus: CertificateStatus | null;
+    createdAt: string;
+    verifiedAt: string | null;
+}