@useatlas/types 0.0.1 → 0.0.3

package/dist/platform.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Platform admin types for cross-tenant management.
+ *
+ * Used by the platform admin console to manage workspaces,
+ * monitor resource usage, and detect noisy neighbors.
+ */
+import type { AtlasRole } from "./auth";
+/** Resolved deploy mode — binary value after auto-detection. */
+export type DeployMode = "saas" | "self-hosted";
+/** Raw deploy mode setting — includes "auto" for auto-detection. */
+export type DeployModeSetting = "saas" | "self-hosted" | "auto";
+export declare const WORKSPACE_STATUSES: readonly ["active", "suspended", "deleted"];
+export type WorkspaceStatus = (typeof WORKSPACE_STATUSES)[number];
+export declare const PLAN_TIERS: readonly ["free", "trial", "team", "enterprise"];
+export type PlanTier = (typeof PLAN_TIERS)[number];
+export declare const NOISY_NEIGHBOR_METRICS: readonly ["queries", "tokens", "storage"];
+export type NoisyNeighborMetric = (typeof NOISY_NEIGHBOR_METRICS)[number];
+export interface PlatformWorkspace {
+    id: string;
+    name: string;
+    slug: string;
+    status: WorkspaceStatus;
+    planTier: PlanTier;
+    byot: boolean;
+    members: number;
+    conversations: number;
+    queriesLast24h: number;
+    connections: number;
+    scheduledTasks: number;
+    stripeCustomerId: string | null;
+    trialEndsAt: string | null;
+    suspendedAt: string | null;
+    deletedAt: string | null;
+    region: string | null;
+    regionAssignedAt: string | null;
+    createdAt: string;
+}
+export interface PlatformWorkspaceDetail {
+    workspace: PlatformWorkspace;
+    users: PlatformWorkspaceUser[];
+}
+export interface PlatformWorkspaceUser {
+    id: string;
+    name: string;
+    email: string;
+    role: AtlasRole;
+    createdAt: string;
+}
+export interface PlatformStats {
+    totalWorkspaces: number;
+    activeWorkspaces: number;
+    suspendedWorkspaces: number;
+    totalUsers: number;
+    totalQueries24h: number;
+    /** Monthly recurring revenue in USD (estimated from plan tiers). */
+    mrr: number;
+}
+export interface NoisyNeighbor {
+    workspaceId: string;
+    workspaceName: string;
+    planTier: PlanTier;
+    metric: NoisyNeighborMetric;
+    value: number;
+    median: number;
+    /** value / median — always > 3 for flagged neighbors. */
+    ratio: number;
+}

package/dist/profiler.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Profiler and wizard types — shared between @atlas/api (snake_case wire format)
+ * and @atlas/web (camelCase UI types).
+ *
+ * Canonical definitions live here; both packages import from @useatlas/types.
+ */
+/** Valid database object types returned by profiler discovery. */
+export declare const OBJECT_TYPES: readonly ["table", "view", "materialized_view"];
+export type ObjectType = (typeof OBJECT_TYPES)[number];
+/** Valid foreign key relationship sources. */
+export declare const FK_SOURCES: readonly ["constraint", "inferred"];
+export type ForeignKeySource = (typeof FK_SOURCES)[number];
+/** Valid partition strategies. */
+export declare const PARTITION_STRATEGIES: readonly ["range", "list", "hash"];
+export type PartitionStrategy = (typeof PARTITION_STRATEGIES)[number];
+export interface ForeignKey {
+    from_column: string;
+    to_table: string;
+    to_column: string;
+    source: ForeignKeySource;
+}
+/**
+ * Column profile from the database profiler.
+ *
+ * Invariant: when `is_foreign_key` is true, `fk_target_table` and
+ * `fk_target_column` are non-null strings. When false, both are null.
+ * This is enforced at construction time in the profiler, not via
+ * discriminated union, to keep the type ergonomic for constructors.
+ */
+export interface ColumnProfile {
+    name: string;
+    type: string;
+    nullable: boolean;
+    unique_count: number | null;
+    null_count: number | null;
+    sample_values: string[];
+    is_primary_key: boolean;
+    is_foreign_key: boolean;
+    fk_target_table: string | null;
+    fk_target_column: string | null;
+    is_enum_like: boolean;
+    profiler_notes: string[];
+}
+/** Heuristic flags set by `analyzeTableProfiles`. */
+export interface TableFlags {
+    possibly_abandoned: boolean;
+    possibly_denormalized: boolean;
+}
+/** Partition metadata for partitioned Postgres tables. */
+export interface PartitionInfo {
+    strategy: PartitionStrategy;
+    key: string;
+    children: string[];
+}
+/**
+ * Table profile from the database profiler.
+ *
+ * `matview_populated` is only present when `object_type === "materialized_view"`.
+ * Check `object_type` before relying on its value.
+ */
+export interface TableProfile {
+    table_name: string;
+    object_type: ObjectType;
+    row_count: number;
+    columns: ColumnProfile[];
+    primary_key_columns: string[];
+    foreign_keys: ForeignKey[];
+    inferred_foreign_keys: ForeignKey[];
+    profiler_notes: string[];
+    table_flags: TableFlags;
+    matview_populated?: boolean;
+    partition_info?: PartitionInfo;
+}
+export interface DatabaseObject {
+    name: string;
+    type: ObjectType;
+}
+export interface ProfileError {
+    table: string;
+    error: string;
+}
+export interface ProfilingResult {
+    profiles: TableProfile[];
+    errors: ProfileError[];
+}
+/** camelCase column info in the wizard generate response. */
+export interface WizardEntityColumn {
+    name: string;
+    type: string;
+    mappedType?: string;
+    nullable: boolean;
+    isPrimaryKey: boolean;
+    isForeignKey: boolean;
+    isEnumLike: boolean;
+    sampleValues: string[];
+    uniqueCount: number | null;
+    nullCount: number | null;
+}
+/** camelCase foreign key in the wizard generate response. */
+export interface WizardForeignKey {
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+    source: ForeignKeySource;
+}
+/** camelCase inferred foreign key in the wizard generate response. */
+export interface WizardInferredForeignKey {
+    fromColumn: string;
+    toTable: string;
+    toColumn: string;
+}
+/** camelCase heuristic flags in the wizard generate response. */
+export interface WizardTableFlags {
+    possiblyAbandoned: boolean;
+    possiblyDenormalized: boolean;
+}
+/** Single entity result from the wizard generate endpoint. */
+export interface WizardEntityResult {
+    tableName: string;
+    objectType: ObjectType;
+    rowCount: number;
+    columnCount: number;
+    yaml: string;
+    profile: {
+        columns: WizardEntityColumn[];
+        primaryKeys: string[];
+        foreignKeys: WizardForeignKey[];
+        inferredForeignKeys: WizardInferredForeignKey[];
+        flags: WizardTableFlags;
+        notes: string[];
+    };
+}
+/** Table entry returned by the wizard profile endpoint. */
+export interface WizardTableEntry {
+    name: string;
+    type: ObjectType;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,27 @@
+/** Prompt library types — wire format for prompt_collections and prompt_items tables. */
+/** All valid prompt industries for built-in collections. */
+export declare const PROMPT_INDUSTRIES: readonly ["saas", "ecommerce", "cybersecurity"];
+export type PromptIndustry = (typeof PROMPT_INDUSTRIES)[number];
+/** Wire format for the prompt_collections table. */
+export interface PromptCollection {
+    id: string;
+    orgId: string | null;
+    name: string;
+    industry: string;
+    description: string;
+    isBuiltin: boolean;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Wire format for the prompt_items table. */
+export interface PromptItem {
+    id: string;
+    collectionId: string;
+    question: string;
+    description: string | null;
+    category: string | null;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/query-suggestion.d.ts

@@ -0,0 +1,16 @@
+/** Query suggestion types — wire format for the query_suggestions table. */
+export interface QuerySuggestion {
+    id: string;
+    orgId: string | null;
+    description: string;
+    patternSql: string;
+    normalizedHash: string;
+    tablesInvolved: string[];
+    primaryTable: string | null;
+    frequency: number;
+    clickedCount: number;
+    score: number;
+    lastSeenAt: string;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/residency.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Data residency types for tenant-to-region routing.
+ *
+ * Used by the platform admin console and enterprise residency module
+ * to assign workspaces to geographic regions and route connections
+ * to region-specific databases.
+ *
+ * Region identifiers are operator-defined via `atlas.config.ts` — the
+ * `WELL_KNOWN_REGIONS` array provides suggestions for the admin UI but
+ * does not constrain which regions can be configured.
+ */
+/**
+ * Well-known region identifiers used as suggestions in the admin UI.
+ * Operators may configure arbitrary region keys in atlas.config.ts.
+ */
+export declare const WELL_KNOWN_REGIONS: readonly ["us-east", "us-west", "eu-west", "eu-central", "ap-southeast", "ap-northeast"];
+/**
+ * Region identifier — an operator-defined string from the residency config.
+ * Not constrained to WELL_KNOWN_REGIONS; any string key in the regions map is valid.
+ */
+export type Region = string;
+export interface RegionConfig {
+    /** Display label shown in the admin console. */
+    label: string;
+    /** PostgreSQL URL for the region's internal database. Region-specific internal routing is planned for a future release. */
+    databaseUrl: string;
+    /** Optional analytics datasource URL override for this region. */
+    datasourceUrl?: string;
+}
+export interface WorkspaceRegion {
+    workspaceId: string;
+    region: Region;
+    /** ISO 8601 timestamp of when the region was assigned. */
+    assignedAt: string;
+}
+/** A region projected for selection UI — safe for the frontend. */
+export interface RegionPickerItem {
+    /** Region identifier (e.g. "us-east", "eu-west"). */
+    id: string;
+    /** Human-readable display label (e.g. "US East", "EU West"). */
+    label: string;
+    /** Whether this region is the deployment's default. */
+    isDefault: boolean;
+}
+/** Valid migration status values — single source of truth for Zod schemas and type. */
+export declare const MIGRATION_STATUSES: readonly ["pending", "in_progress", "completed", "failed"];
+/** Status of a region migration request. */
+export type MigrationStatus = (typeof MIGRATION_STATUSES)[number];
+/** A workspace region migration request. */
+export interface RegionMigration {
+    id: string;
+    workspaceId: string;
+    sourceRegion: Region;
+    targetRegion: Region;
+    status: MigrationStatus;
+    /** User ID of who requested the migration. */
+    requestedBy: string | null;
+    /** ISO 8601 timestamp of when the migration was requested. */
+    requestedAt: string;
+    /** ISO 8601 timestamp of when the migration completed (or failed). */
+    completedAt: string | null;
+    /** Error message if the migration failed. */
+    errorMessage: string | null;
+}
+export interface RegionStatus {
+    region: Region;
+    label: string;
+    workspaceCount: number;
+    /** Always true in current implementation. Reserved for future health checks. */
+    healthy: boolean;
+}

package/dist/semantic.d.ts

@@ -1,4 +1,5 @@
 /** Semantic layer entity types — dimensions, joins, measures, query patterns, and entity shapes. */
+import type { PIICategory, PIIConfidence } from "./compliance";
 /** Valid dimension types per the semantic layer YAML spec. */
 export type DimensionType = "string" | "number" | "date" | "boolean" | "timestamp";
 export interface Dimension {
@@ -8,6 +9,10 @@ export interface Dimension {
     sample_values?: string[];
     primary_key?: boolean;
     foreign_key?: boolean;
+    /** PII category detected during profiling. Enterprise feature. Must be set together with pii_confidence. */
+    pii?: PIICategory | (string & {});
+    /** PII detection confidence level. Must be set together with pii. */
+    pii_confidence?: PIIConfidence | (string & {});
 }
 export interface Join {
     to: string;
@@ -45,3 +50,51 @@ export interface SemanticEntityDetail {
 export interface EntityData extends SemanticEntityDetail {
     name: string;
 }
+/** Column-level diff for a single table that exists in both DB and YAML. */
+export interface SemanticTableDiff {
+    table: string;
+    addedColumns: {
+        name: string;
+        type: string;
+    }[];
+    removedColumns: {
+        name: string;
+        type: string;
+    }[];
+    typeChanges: {
+        name: string;
+        yamlType: string;
+        dbType: string;
+    }[];
+}
+/** Full diff result returned by `GET /api/v1/admin/semantic/diff`. */
+export interface SemanticDiffResponse {
+    connection: string;
+    newTables: string[];
+    removedTables: string[];
+    tableDiffs: SemanticTableDiff[];
+    unchangedCount: number;
+    summary: {
+        total: number;
+        new: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+    };
+    warnings?: string[];
+}
+/** Column info returned by the public tables endpoint. */
+export interface TableColumn {
+    name: string;
+    type: DimensionType | (string & {});
+    description: string;
+}
+/**
+ * Simplified table info returned by the public `GET /api/v1/tables` endpoint.
+ * A projection of `SemanticEntityDetail` exposing only dimensions (as columns).
+ */
+export interface TableInfo {
+    table: string;
+    description: string;
+    columns: TableColumn[];
+}

package/dist/share.d.ts

@@ -1,5 +1,19 @@
+/** Share visibility mode. */
+export declare const SHARE_MODES: readonly ["public", "org"];
+export type ShareMode = (typeof SHARE_MODES)[number];
+/** Predefined expiry durations for share links (in seconds). */
+export declare const SHARE_EXPIRY_OPTIONS: {
+    readonly "1h": 3600;
+    readonly "24h": 86400;
+    readonly "7d": 604800;
+    readonly "30d": 2592000;
+    readonly never: null;
+};
+export type ShareExpiryKey = keyof typeof SHARE_EXPIRY_OPTIONS;
 /** Response shape when generating a shareable link for a conversation. */
 export interface ShareLink {
     token: string;
     url: string;
+    expiresAt: string | null;
+    shareMode: ShareMode;
 }

package/dist/share.js

@@ -0,0 +1,13 @@
+// src/share.ts
+var SHARE_MODES = ["public", "org"];
+var SHARE_EXPIRY_OPTIONS = {
+  "1h": 3600,
+  "24h": 86400,
+  "7d": 604800,
+  "30d": 2592000,
+  never: null
+};
+export {
+  SHARE_MODES,
+  SHARE_EXPIRY_OPTIONS
+};

package/dist/sla.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SLA monitoring and alerting types.
+ *
+ * Used by platform admin console for per-workspace uptime,
+ * query latency, error rate tracking, and alerting.
+ */
+/** Aggregated SLA metrics for a single workspace. */
+export interface WorkspaceSLASummary {
+    workspaceId: string;
+    workspaceName: string;
+    latencyP50Ms: number;
+    latencyP95Ms: number;
+    latencyP99Ms: number;
+    /** Error rate as a percentage (0–100). */
+    errorRatePct: number;
+    /** Uptime as a percentage (0–100), derived from successful query ratio. */
+    uptimePct: number;
+    totalQueries: number;
+    failedQueries: number;
+    lastQueryAt: string | null;
+}
+/** A single metric data point for time-series charts. */
+export interface SLAMetricPoint {
+    timestamp: string;
+    value: number;
+}
+/** Per-workspace detail view with time-series data. */
+export interface WorkspaceSLADetail {
+    summary: WorkspaceSLASummary;
+    latencyTimeline: SLAMetricPoint[];
+    errorTimeline: SLAMetricPoint[];
+}
+export declare const SLA_ALERT_STATUSES: readonly ["firing", "resolved", "acknowledged"];
+export type SLAAlertStatus = (typeof SLA_ALERT_STATUSES)[number];
+export declare const SLA_ALERT_TYPES: readonly ["latency_p99", "error_rate"];
+export type SLAAlertType = (typeof SLA_ALERT_TYPES)[number];
+export interface SLAAlert {
+    id: string;
+    workspaceId: string;
+    workspaceName: string;
+    type: SLAAlertType;
+    status: SLAAlertStatus;
+    /** Current metric value that triggered the alert (ms for latency, % for error rate). */
+    currentValue: number;
+    /** Threshold that was exceeded (same unit as currentValue). */
+    threshold: number;
+    message: string;
+    firedAt: string;
+    resolvedAt: string | null;
+    acknowledgedAt: string | null;
+    acknowledgedBy: string | null;
+}
+export interface SLAThresholds {
+    /** P99 latency threshold in milliseconds. */
+    latencyP99Ms: number;
+    /** Error rate threshold as a percentage (0–100). */
+    errorRatePct: number;
+}

package/dist/sso.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Enterprise SSO types shared across API, frontend, and SDK.
+ *
+ * SSO providers are org-scoped: each organization can register one or more
+ * SAML/OIDC identity providers for single sign-on. Domain-based
+ * auto-provisioning maps email domains to organizations.
+ */
+export declare const SSO_PROVIDER_TYPES: readonly ["saml", "oidc"];
+export type SSOProviderType = (typeof SSO_PROVIDER_TYPES)[number];
+/** SAML-specific configuration stored in sso_providers.config JSONB. */
+export interface SSOSamlConfig {
+    /** IdP Entity ID (issuer). */
+    idpEntityId: string;
+    /** IdP Single Sign-On URL (HTTP-Redirect or HTTP-POST binding). */
+    idpSsoUrl: string;
+    /** IdP X.509 certificate in PEM format for signature verification. */
+    idpCertificate: string;
+    /** SP Entity ID. Must be configured explicitly when initiating SAML flows. */
+    spEntityId?: string;
+    /** SP Assertion Consumer Service URL. */
+    spAcsUrl?: string;
+}
+/** OIDC-specific configuration stored in sso_providers.config JSONB. */
+export interface SSOOidcConfig {
+    /** OAuth2 Client ID. */
+    clientId: string;
+    /** OAuth2 Client Secret (encrypted at rest in the sso_providers.config column). */
+    clientSecret: string;
+    /** OpenID Connect Discovery URL (e.g. `https://idp.example.com/.well-known/openid-configuration`). */
+    discoveryUrl: string;
+}
+interface SSOProviderBase {
+    id: string;
+    orgId: string;
+    /** IdP issuer identifier (entityId for SAML, issuer URL for OIDC). */
+    issuer: string;
+    /** Email domain for auto-provisioning (e.g. "acme.com"). */
+    domain: string;
+    enabled: boolean;
+    /** When true, password login is blocked for this org — users must use SSO. */
+    ssoEnforced: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SSOSamlProvider extends SSOProviderBase {
+    type: "saml";
+    config: SSOSamlConfig;
+}
+export interface SSOOidcProvider extends SSOProviderBase {
+    type: "oidc";
+    config: SSOOidcConfig;
+}
+/** Discriminated union — `type` determines the shape of `config`. */
+export type SSOProvider = SSOSamlProvider | SSOOidcProvider;
+export type CreateSSOProviderRequest = {
+    type: "saml";
+    issuer: string;
+    domain: string;
+    enabled?: boolean;
+    config: SSOSamlConfig;
+} | {
+    type: "oidc";
+    issuer: string;
+    domain: string;
+    enabled?: boolean;
+    config: SSOOidcConfig;
+};
+export interface UpdateSSOProviderRequest {
+    issuer?: string;
+    domain?: string;
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+}
+/** Response shape for list endpoints. Currently total equals providers.length (no pagination yet). */
+export interface SSOProviderListResponse {
+    providers: SSOProvider[];
+    total: number;
+}
+export {};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@useatlas/types",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Shared types for the Atlas text-to-SQL agent",
   "type": "module",
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/auth.ts src/conversation.ts src/connection.ts src/action.ts src/scheduled-task.ts src/errors.ts src/semantic.ts src/share.ts --outdir dist --root src --target node --packages external && npx tsc -p tsconfig.build.json"
+    "build": "rm -rf dist && bun build src/index.ts src/auth.ts src/conversation.ts src/connection.ts src/action.ts src/scheduled-task.ts src/errors.ts src/semantic.ts src/share.ts src/billing.ts --outdir dist --root src --target node --packages external && bun x tsc -p tsconfig.build.json"
   },
   "exports": {
     ".": {
@@ -51,6 +51,11 @@
       "types": "./dist/share.d.ts",
       "import": "./dist/share.js",
       "default": "./dist/share.js"
+    },
+    "./billing": {
+      "types": "./dist/billing.d.ts",
+      "import": "./dist/billing.js",
+      "default": "./dist/billing.js"
     }
   },
   "main": "./dist/index.js",