fraiseql 2.1.1

package/dist/index.d.mts

@@ -0,0 +1,1688 @@
+/**
+ * Type mapping and introspection for GraphQL schema generation.
+ *
+ * This module converts TypeScript type annotations to GraphQL type strings,
+ * enabling compile-time schema generation without runtime overhead.
+ */
+/**
+ * Convert TypeScript type to GraphQL type string.
+ *
+ * @param type - TypeScript type annotation
+ * @returns Tuple of [graphql_type, is_nullable]
+ *
+ * @example
+ * typeToGraphQL(String) => ["String", false]
+ * typeToGraphQL(String | null) => ["String", true]
+ * typeToGraphQL(Array<User>) => ["[User!]", false]
+ */
+declare function typeToGraphQL(type: unknown): [graphqlType: string, nullable: boolean];
+/**
+ * Field information extracted from a class with type metadata.
+ */
+interface FieldInfo {
+    type: string;
+    nullable: boolean;
+}
+/**
+ * Extract field information from class property metadata.
+ *
+ * @param fields - Dictionary mapping field names to type annotations
+ * @returns Dictionary of field_name -> FieldInfo
+ *
+ * @example
+ * const fields = {
+ *   id: "number",
+ *   name: "string",
+ *   email: "string | null"
+ * };
+ * extractFieldInfo(fields) => {
+ *   id: { type: "Int", nullable: false },
+ *   name: { type: "String", nullable: false },
+ *   email: { type: "String", nullable: true }
+ * }
+ */
+declare function extractFieldInfo(fields: Record<string, unknown>): Record<string, FieldInfo>;
+/**
+ * Argument information for a function parameter.
+ */
+interface ArgumentInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    default?: unknown;
+}
+/**
+ * Return type information for a function.
+ */
+interface ReturnTypeInfo {
+    type: string;
+    nullable: boolean;
+    isList: boolean;
+}
+/**
+ * Function signature information extracted from a decorated function.
+ */
+interface FunctionSignature {
+    arguments: ArgumentInfo[];
+    returnType: ReturnTypeInfo;
+}
+/**
+ * Extract GraphQL-relevant information from function signature.
+ *
+ * @param name - Function name
+ * @param params - Dictionary mapping parameter names to type annotations
+ * @param returnType - Return type annotation
+ * @returns FunctionSignature with arguments and return type info
+ *
+ * @example
+ * extractFunctionSignature(
+ *   "users",
+ *   { limit: "number", offset: "number" },
+ *   "User[]"
+ * ) => {
+ *   arguments: [
+ *     { name: "limit", type: "Int", nullable: false },
+ *     { name: "offset", type: "Int", nullable: false }
+ *   ],
+ *   returnType: { type: "[User!]", nullable: false, isList: true }
+ * }
+ */
+declare function extractFunctionSignature(_name: string, params: Record<string, unknown>, returnType: unknown): FunctionSignature;
+
+/**
+ * FraiseQL scalar type markers for schema authoring.
+ *
+ * These are branded type aliases used in TypeScript to generate the correct
+ * GraphQL scalar types in schema.json. They have no runtime behavior - validation
+ * and serialization happen in the Rust runtime after compilation.
+ *
+ * Architecture:
+ *   TypeScript type annotation → schema.json type string → Rust FieldType → codegen/introspection
+ *
+ * @example
+ * ```typescript
+ * import { Type } from "fraiseql";
+ * import { ID, DateTime, Email, URL } from "fraiseql/scalars";
+ *
+ * @Type()
+ * class User {
+ *   id: ID;                    // → "ID" in schema.json → FieldType::Id
+ *   name: string;              // → "String"
+ *   email: Email;              // → "Email" → FieldType::Scalar("Email")
+ *   website: URL | null;       // → "URL" (nullable)
+ *   createdAt: DateTime;       // → "DateTime" → FieldType::DateTime
+ * }
+ * ```
+ *
+ * FraiseQL Convention:
+ *   - `id` fields should ALWAYS use `ID` type (UUID v4 at runtime)
+ *   - Foreign keys (e.g., `authorId`) should also use `ID`
+ *
+ * Custom Scalars:
+ *   You can define your own custom scalars using branded types:
+ *
+ *   ```typescript
+ *   type MyCustomScalar = string & { readonly __brand: "MyCustomScalar" };
+ *   ```
+ *
+ *   The scalar name will pass through to schema.json and be validated at runtime.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Abstract base class for custom GraphQL scalars with validation.
+ *
+ * Subclasses must define a `name` property and implement
+ * the three validation methods (serialize, parseValue, parseLiteral).
+ *
+ * Use with the @Scalar decorator to register custom scalars with the schema.
+ *
+ * @example
+ * ```typescript
+ * class Email extends CustomScalar {
+ *   name = "Email"
+ *
+ *   serialize(value: unknown): string {
+ *     return String(value)
+ *   }
+ *
+ *   parseValue(value: unknown): string {
+ *     const str = String(value)
+ *     if (!str.includes("@")) {
+ *       throw new Error("Invalid email address")
+ *     }
+ *     return str
+ *   }
+ *
+ *   parseLiteral(ast: unknown): string {
+ *     if (ast && typeof ast === "object" && "value" in ast) {
+ *       return this.parseValue((ast as any).value)
+ *     }
+ *     throw new Error("Invalid email literal")
+ *   }
+ * }
+ * ```
+ */
+declare abstract class CustomScalar {
+    /**
+     * Scalar name (e.g., "Email"). Must be unique in schema.
+     */
+    abstract name: string;
+    /**
+     * Convert value to output format (schema → response).
+     *
+     * Called when serializing a field value in GraphQL response.
+     *
+     * @param value - The internal representation (from database/object)
+     * @returns The value formatted for GraphQL response (usually string)
+     * @throws If value cannot be serialized
+     *
+     * @example
+     * ```typescript
+     * serialize(value: Date): string {
+     *   return value.toISOString()
+     * }
+     * ```
+     */
+    abstract serialize(value: unknown): unknown;
+    /**
+     * Validate and convert input value (client input → internal).
+     *
+     * Called when a scalar is passed as a variable in GraphQL query.
+     *
+     * @param value - Raw input value from client
+     * @returns Validated/converted value
+     * @throws If validation fails
+     *
+     * @example
+     * ```typescript
+     * parseValue(value: unknown): string {
+     *   const str = String(value)
+     *   if (!str.includes("@")) {
+     *     throw new Error("Invalid email address")
+     *   }
+     *   return str
+     * }
+     * ```
+     */
+    abstract parseValue(value: unknown): unknown;
+    /**
+     * Parse GraphQL literal (hardcoded value in query).
+     *
+     * Called when a scalar is hardcoded in the GraphQL query string
+     * (not as a variable).
+     *
+     * @param ast - GraphQL AST node representing the literal
+     * @returns Validated/converted value
+     * @throws If literal cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * parseLiteral(ast: unknown): string {
+     *   if (ast && typeof ast === "object" && "value" in ast) {
+     *     return this.parseValue((ast as any).value)
+     *   }
+     *   throw new Error(`Invalid email literal: ${ast}`)
+     * }
+     * ```
+     */
+    abstract parseLiteral(ast: unknown): unknown;
+}
+/**
+ * Creates a branded type for nominal typing.
+ * This allows TypeScript to distinguish between different scalar types at compile time.
+ */
+type Brand<T, B extends string> = T & {
+    readonly __brand: B;
+};
+/**
+ * GraphQL ID scalar - used for unique identifiers.
+ *
+ * FraiseQL enforces UUID v4 format for all ID fields at runtime.
+ * This is the REQUIRED type for `id` fields and foreign key references.
+ */
+type ID = Brand<string, "ID">;
+/** ISO 8601 DateTime scalar (e.g., "2025-01-10T12:00:00Z"). */
+type DateTime = Brand<string, "DateTime">;
+/** ISO 8601 Date scalar (e.g., "2025-01-10"). */
+type Date = Brand<string, "Date">;
+/** ISO 8601 Time scalar (e.g., "12:00:00"). */
+type Time = Brand<string, "Time">;
+/** Date range scalar (e.g., "[2025-01-01,2025-12-31)"). */
+type DateRange = Brand<string, "DateRange">;
+/** ISO 8601 Duration scalar (e.g., "P1Y2M3D"). */
+type Duration = Brand<string, "Duration">;
+/** Arbitrary JSON value scalar. Maps to PostgreSQL JSONB. */
+type Json = Brand<unknown, "Json">;
+/** UUID scalar (explicit UUID type, distinct from ID). */
+type UUID = Brand<string, "UUID">;
+/** Decimal/BigDecimal scalar for precise numeric values. */
+type Decimal = Brand<string, "Decimal">;
+/** Vector scalar for pgvector embeddings. */
+type Vector = Brand<number[], "Vector">;
+/** Email address scalar with RFC 5322 validation. */
+type Email = Brand<string, "Email">;
+/** Phone number scalar (E.164 format recommended). */
+type PhoneNumber = Brand<string, "PhoneNumber">;
+/** URL scalar with RFC 3986 validation. */
+type URL = Brand<string, "URL">;
+/** Domain name scalar. */
+type DomainName = Brand<string, "DomainName">;
+/** Hostname scalar. */
+type Hostname = Brand<string, "Hostname">;
+/** Postal/ZIP code scalar. */
+type PostalCode = Brand<string, "PostalCode">;
+/** Latitude coordinate (-90 to 90). */
+type Latitude = Brand<number, "Latitude">;
+/** Longitude coordinate (-180 to 180). */
+type Longitude = Brand<number, "Longitude">;
+/** Geographic coordinates scalar (lat,lng or GeoJSON). */
+type Coordinates = Brand<string, "Coordinates">;
+/** IANA timezone identifier (e.g., "America/New_York"). */
+type Timezone = Brand<string, "Timezone">;
+/** Locale code scalar (e.g., "en-US"). */
+type LocaleCode = Brand<string, "LocaleCode">;
+/** ISO 639-1 language code (e.g., "en"). */
+type LanguageCode = Brand<string, "LanguageCode">;
+/** ISO 3166-1 alpha-2 country code (e.g., "US"). */
+type CountryCode = Brand<string, "CountryCode">;
+/** International Bank Account Number. */
+type IBAN = Brand<string, "IBAN">;
+/** CUSIP identifier for North American securities. */
+type CUSIP = Brand<string, "CUSIP">;
+/** International Securities Identification Number. */
+type ISIN = Brand<string, "ISIN">;
+/** Stock Exchange Daily Official List number. */
+type SEDOL = Brand<string, "SEDOL">;
+/** Legal Entity Identifier. */
+type LEI = Brand<string, "LEI">;
+/** Market Identifier Code. */
+type MIC = Brand<string, "MIC">;
+/** ISO 4217 currency code (e.g., "USD"). */
+type CurrencyCode = Brand<string, "CurrencyCode">;
+/** Monetary amount with currency (e.g., "USD 100.00"). */
+type Money = Brand<string, "Money">;
+/** Stock exchange code. */
+type ExchangeCode = Brand<string, "ExchangeCode">;
+/** Currency exchange rate. */
+type ExchangeRate = Brand<string, "ExchangeRate">;
+/** Stock ticker symbol. */
+type StockSymbol = Brand<string, "StockSymbol">;
+/** Percentage value (0-100 or 0-1 depending on context). */
+type Percentage = Brand<number, "Percentage">;
+/** URL-safe slug (lowercase, hyphens, no spaces). */
+type Slug = Brand<string, "Slug">;
+/** Semantic version string (e.g., "1.2.3"). */
+type SemanticVersion = Brand<string, "SemanticVersion">;
+/** SHA-256 hash string (64 hex characters). */
+type HashSHA256 = Brand<string, "HashSHA256">;
+/** API key string. */
+type APIKey = Brand<string, "APIKey">;
+/** Vehicle license plate number. */
+type LicensePlate = Brand<string, "LicensePlate">;
+/** Vehicle Identification Number. */
+type VIN = Brand<string, "VIN">;
+/** Shipping tracking number. */
+type TrackingNumber = Brand<string, "TrackingNumber">;
+/** Shipping container number (ISO 6346). */
+type ContainerNumber = Brand<string, "ContainerNumber">;
+/** IP address (IPv4 or IPv6). */
+type IPAddress = Brand<string, "IPAddress">;
+/** IPv4 address. */
+type IPv4 = Brand<string, "IPv4">;
+/** IPv6 address. */
+type IPv6 = Brand<string, "IPv6">;
+/** MAC address. */
+type MACAddress = Brand<string, "MACAddress">;
+/** CIDR notation for IP ranges. */
+type CIDR = Brand<string, "CIDR">;
+/** Network port number (0-65535). */
+type Port = Brand<number, "Port">;
+/** IATA airport code (e.g., "JFK"). */
+type AirportCode = Brand<string, "AirportCode">;
+/** UN/LOCODE port code. */
+type PortCode = Brand<string, "PortCode">;
+/** Flight number (e.g., "AA123"). */
+type FlightNumber = Brand<string, "FlightNumber">;
+/** Markdown-formatted text. */
+type Markdown = Brand<string, "Markdown">;
+/** HTML-formatted text. */
+type HTML = Brand<string, "HTML">;
+/** MIME type (e.g., "application/json"). */
+type MimeType = Brand<string, "MimeType">;
+/** Color value (hex, RGB, or named). */
+type Color = Brand<string, "Color">;
+/** Image reference (URL or base64). */
+type Image = Brand<string, "Image">;
+/** File reference (URL or path). */
+type File = Brand<string, "File">;
+/** PostgreSQL ltree path (e.g., "root.child.leaf"). */
+type LTree = Brand<string, "LTree">;
+/**
+ * Set of all known scalar type names.
+ * Used by the type system to recognize scalar types.
+ */
+declare const SCALAR_NAMES: Set<string>;
+/**
+ * Check if a type name is a known scalar type.
+ */
+declare function isScalarType(typeName: string): boolean;
+
+/**
+ * Global schema registry for collecting types, queries, and mutations.
+ *
+ * This module maintains a singleton registry of all definitions made via decorators,
+ * which is then exported to schema.json for compilation.
+ */
+
+/**
+ * Field metadata for access control and deprecation.
+ */
+interface FieldMetadata {
+    requiresScope?: string | string[];
+    deprecated?: boolean | string;
+    description?: string;
+}
+/**
+ * Field definition in a GraphQL type.
+ */
+interface Field extends FieldMetadata {
+    name: string;
+    type: string;
+    nullable: boolean;
+    default?: unknown;
+}
+/**
+ * GraphQL type definition.
+ */
+interface TypeDefinition {
+    name: string;
+    fields: Field[];
+    description?: string;
+    relay?: boolean;
+    sql_source?: string;
+    jsonb_column?: string;
+    is_error?: boolean;
+    requires_role?: string;
+    implements?: string[];
+}
+/**
+ * Argument definition for a query or mutation.
+ */
+interface ArgumentDefinition {
+    name: string;
+    type: string;
+    nullable: boolean;
+    default?: unknown;
+}
+/**
+ * GraphQL query definition.
+ */
+interface QueryDefinition {
+    name: string;
+    return_type: string;
+    returns_list: boolean;
+    nullable: boolean;
+    arguments: ArgumentDefinition[];
+    description?: string;
+    [key: string]: unknown;
+}
+/**
+ * GraphQL mutation definition.
+ */
+interface MutationDefinition {
+    name: string;
+    return_type: string;
+    returns_list: boolean;
+    nullable: boolean;
+    arguments: ArgumentDefinition[];
+    description?: string;
+    operation?: string;
+    [key: string]: unknown;
+}
+/**
+ * Measure definition in a fact table.
+ */
+interface Measure {
+    name: string;
+    sql_type: string;
+    nullable: boolean;
+}
+/**
+ * Dimension path in a fact table.
+ */
+interface DimensionPath {
+    name: string;
+    json_path: string;
+    data_type: string;
+}
+/**
+ * Dimension definition in a fact table.
+ */
+interface Dimension {
+    name: string;
+    paths: DimensionPath[];
+}
+/**
+ * Denormalized filter in a fact table.
+ */
+interface DenormalizedFilter {
+    name: string;
+    sql_type: string;
+    indexed: boolean;
+}
+/**
+ * Fact table definition.
+ */
+interface FactTableDefinition {
+    table_name: string;
+    measures: Measure[];
+    dimensions: Dimension;
+    denormalized_filters: DenormalizedFilter[];
+}
+/**
+ * Aggregate query definition.
+ */
+interface AggregateQueryDefinition {
+    name: string;
+    fact_table: string;
+    auto_group_by: boolean;
+    auto_aggregates: boolean;
+    description?: string;
+}
+/**
+ * GraphQL subscription definition.
+ *
+ * Subscriptions in FraiseQL are compiled projections of database events.
+ * They are sourced from LISTEN/NOTIFY or CDC, not resolver-based.
+ */
+interface SubscriptionDefinition {
+    name: string;
+    entity_type: string;
+    nullable: boolean;
+    arguments: ArgumentDefinition[];
+    description?: string;
+    topic?: string;
+    operation?: string;
+    [key: string]: unknown;
+}
+/**
+ * Observer action definition.
+ */
+interface ObserverAction {
+    type: "webhook" | "slack" | "email";
+    [key: string]: unknown;
+}
+/**
+ * Observer retry configuration.
+ */
+interface ObserverRetryConfig {
+    max_attempts: number;
+    backoff_strategy: string;
+    initial_delay_ms: number;
+    max_delay_ms: number;
+}
+/**
+ * Observer definition.
+ */
+interface ObserverDefinition {
+    name: string;
+    entity: string;
+    event: string;
+    actions: ObserverAction[];
+    condition?: string;
+    retry: ObserverRetryConfig;
+}
+/**
+ * Enum value definition.
+ */
+interface EnumValue {
+    name: string;
+    deprecated?: {
+        reason: string;
+    };
+}
+/**
+ * GraphQL enum definition.
+ */
+interface EnumDefinition {
+    name: string;
+    values: EnumValue[];
+    description?: string;
+}
+/**
+ * GraphQL interface definition.
+ */
+interface InterfaceDefinition {
+    name: string;
+    fields: Field[];
+    description?: string;
+}
+/**
+ * GraphQL input type definition.
+ */
+interface InputTypeDefinition {
+    name: string;
+    fields: Array<Field & {
+        default?: unknown;
+    }>;
+    description?: string;
+}
+/**
+ * GraphQL union definition.
+ */
+interface UnionDefinition {
+    name: string;
+    member_types: string[];
+    description?: string;
+}
+/**
+ * Complete schema definition.
+ */
+interface Schema {
+    types: TypeDefinition[];
+    queries: QueryDefinition[];
+    mutations: MutationDefinition[];
+    subscriptions: SubscriptionDefinition[];
+    enums?: EnumDefinition[];
+    interfaces?: InterfaceDefinition[];
+    input_types?: InputTypeDefinition[];
+    unions?: UnionDefinition[];
+    fact_tables?: FactTableDefinition[];
+    aggregate_queries?: AggregateQueryDefinition[];
+    observers?: ObserverDefinition[];
+    /** Apollo Federation v2 metadata, included when generateSchemaJson() is used. */
+    federation?: {
+        enabled: boolean;
+        version: string;
+        [key: string]: unknown;
+    };
+    /** Custom scalar definitions, included when scalars are registered. */
+    customScalars?: Record<string, {
+        name: string;
+        description: string;
+        validate: boolean;
+    }>;
+}
+/**
+ * Global schema registry (singleton).
+ *
+ * Maintains maps of all registered types, queries, mutations, and analytics definitions.
+ * These are collected during decorator evaluation and exported to schema.json.
+ */
+declare class SchemaRegistry {
+    private static types;
+    private static queries;
+    private static mutations;
+    private static subscriptions;
+    private static enums;
+    private static interfaces;
+    private static inputTypes;
+    private static unions;
+    private static factTables;
+    private static aggregateQueries;
+    private static observers;
+    private static customScalars;
+    /**
+     * Register a GraphQL type.
+     *
+     * @param name - Type name (e.g., "User")
+     * @param fields - List of field definitions
+     * @param description - Optional type description
+     * @param options - Additional type options
+     */
+    static registerType(name: string, fields: Field[], description?: string, options?: {
+        relay?: boolean;
+        sqlSource?: string;
+        jsonbColumn?: string;
+        isError?: boolean;
+        requiresRole?: string;
+        implements?: string[];
+    }): void;
+    /**
+     * Register a GraphQL query.
+     *
+     * @param name - Query name
+     * @param returnType - Return type name
+     * @param returnsList - Whether query returns a list
+     * @param nullable - Whether result can be null
+     * @param args - List of argument definitions
+     * @param description - Optional query description
+     * @param config - Additional configuration (sql_source, etc.)
+     */
+    static registerQuery(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+    /**
+     * Register a GraphQL mutation.
+     *
+     * @param name - Mutation name
+     * @param returnType - Return type name
+     * @param returnsList - Whether mutation returns a list
+     * @param nullable - Whether result can be null
+     * @param args - List of argument definitions
+     * @param description - Optional mutation description
+     * @param config - Additional configuration (sql_source, operation, etc.)
+     */
+    static registerMutation(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+    /**
+     * Register a GraphQL subscription.
+     *
+     * Subscriptions in FraiseQL are compiled projections of database events.
+     * They are sourced from LISTEN/NOTIFY or CDC, not resolver-based.
+     *
+     * @param name - Subscription name
+     * @param entityType - Entity type name being subscribed to
+     * @param nullable - Whether result can be null
+     * @param args - List of argument definitions (filters)
+     * @param description - Optional subscription description
+     * @param config - Additional configuration (topic, operation, etc.)
+     */
+    static registerSubscription(name: string, entityType: string, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+    /**
+     * Register a fact table definition.
+     *
+     * @param tableName - Fact table name
+     * @param measures - List of measure definitions
+     * @param dimensions - Dimension metadata
+     * @param denormalizedFilters - List of denormalized filter definitions
+     */
+    static registerFactTable(tableName: string, measures: Measure[], dimensions: Dimension, denormalizedFilters: DenormalizedFilter[]): void;
+    /**
+     * Register an aggregate query definition.
+     *
+     * @param name - Query name
+     * @param factTable - Fact table name
+     * @param autoGroupBy - Auto-generate groupBy fields
+     * @param autoAggregates - Auto-generate aggregate fields
+     * @param description - Optional query description
+     */
+    static registerAggregateQuery(name: string, factTable: string, autoGroupBy: boolean, autoAggregates: boolean, description?: string): void;
+    /**
+     * Register an observer.
+     *
+     * @param name - Observer function name
+     * @param entity - Entity type to observe
+     * @param event - Event type (INSERT, UPDATE, or DELETE)
+     * @param actions - List of action configurations
+     * @param condition - Optional condition expression
+     * @param retry - Retry configuration
+     */
+    static registerObserver(name: string, entity: string, event: string, actions: ObserverAction[], condition?: string, retry?: ObserverRetryConfig): void;
+    /**
+     * Register a GraphQL enum type.
+     *
+     * @param name - Enum name (e.g., "OrderStatus")
+     * @param values - List of enum value definitions
+     * @param description - Optional enum description
+     */
+    static registerEnum(name: string, values: EnumValue[], description?: string): void;
+    /**
+     * Register a GraphQL interface type.
+     *
+     * @param name - Interface name (e.g., "Node")
+     * @param fields - List of field definitions
+     * @param description - Optional interface description
+     */
+    static registerInterface(name: string, fields: Field[], description?: string): void;
+    /**
+     * Register a GraphQL input type.
+     *
+     * @param name - Input type name (e.g., "CreateUserInput")
+     * @param fields - List of field definitions with optional defaults
+     * @param description - Optional input type description
+     */
+    static registerInputType(name: string, fields: Array<Field & {
+        default?: unknown;
+    }>, description?: string): void;
+    /**
+     * Register a GraphQL union type.
+     *
+     * @param name - Union name (e.g., "SearchResult")
+     * @param memberTypes - List of member type names
+     * @param description - Optional union description
+     */
+    static registerUnion(name: string, memberTypes: string[], description?: string): void;
+    /**
+     * Register a custom scalar.
+     *
+     * @param name - Scalar name (e.g., "Email")
+     * @param scalarClass - The CustomScalar subclass
+     * @param description - Optional scalar description
+     *
+     * @throws If scalar name is not unique
+     */
+    static registerScalar(name: string, scalarClass: typeof CustomScalar, description?: string): void;
+    /**
+     * Get all registered custom scalars.
+     *
+     * @returns Map of scalar names to CustomScalar classes
+     */
+    static getCustomScalars(): Map<string, typeof CustomScalar>;
+    /**
+     * Get the complete schema as an object.
+     *
+     * @returns Schema object with types, queries, mutations, subscriptions, and analytics sections
+     */
+    static getSchema(): Schema;
+    /**
+     * Clear the registry (useful for testing).
+     */
+    static clear(): void;
+}
+
+/**
+ * Decorators for FraiseQL schema authoring (compile-time only).
+ *
+ * These decorators register type and query definitions with the schema registry
+ * for JSON export. NO runtime behavior - only metadata collection.
+ */
+
+/**
+ * Create field-level metadata for access control and deprecation.
+ *
+ * This function creates metadata for use with field definitions to add:
+ * - `requiresScope`: JWT scope required to access this field
+ * - `deprecated`: Deprecation marker with optional reason
+ * - `description`: Field description for GraphQL schema
+ *
+ * @param options - Field metadata options
+ * @returns Field metadata object
+ *
+ * @example
+ * ```typescript
+ * fraiseql.registerTypeFields("User", [
+ *   { name: "id", type: "ID", nullable: false },
+ *   {
+ *     name: "salary",
+ *     type: "Decimal",
+ *     nullable: false,
+ *     requiresScope: "read:User.salary"  // Requires JWT scope
+ *   },
+ *   {
+ *     name: "oldEmail",
+ *     type: "String",
+ *     nullable: true,
+ *     deprecated: "Use email instead"  // Deprecation marker
+ *   }
+ * ]);
+ * ```
+ */
+declare function field(options: FieldMetadata): FieldMetadata;
+/**
+ * Configuration for a Type decorator.
+ */
+interface TypeConfig {
+    description?: string;
+    relay?: boolean;
+    sqlSource?: string;
+    crud?: boolean | string[];
+    cascade?: boolean;
+}
+/**
+ * Decorator to mark a class as a GraphQL type.
+ *
+ * This decorator registers the class with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @param config - Optional configuration
+ * @returns Decorator function
+ *
+ * @example
+ * ```ts
+ * @Type()
+ * class User {
+ *   id: number;
+ *   name: string;
+ *   email: string | null;
+ * }
+ * ```
+ *
+ * This generates JSON:
+ * ```json
+ * {
+ *   "name": "User",
+ *   "fields": [
+ *     {"name": "id", "type": "Int", "nullable": false},
+ *     {"name": "name", "type": "String", "nullable": false},
+ *     {"name": "email", "type": "String", "nullable": true}
+ *   ]
+ * }
+ * ```
+ */
+declare function Type(_config?: TypeConfig): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => T;
+/**
+ * Configuration for Query and Mutation decorators.
+ */
+interface OperationConfig {
+    sqlSource?: string;
+    autoParams?: Record<string, boolean>;
+    operation?: string;
+    jsonbColumn?: string;
+    relay?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Decorator to mark a function as a GraphQL query.
+ *
+ * This decorator registers the function with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * Configuration is provided via parameters:
+ * - sqlSource: SQL view name or table name
+ * - autoParams: Auto-parameter configuration
+ * - Other configuration as needed
+ *
+ * @param config - Query configuration
+ * @returns Decorator function
+ *
+ * @example
+ * ```ts
+ * @Query({ sqlSource: "v_user" })
+ * function users(limit: number = 10, offset: number = 0): User[] {
+ *   pass;
+ * }
+ * ```
+ *
+ * This generates JSON:
+ * ```json
+ * {
+ *   "name": "users",
+ *   "return_type": "User",
+ *   "returns_list": true,
+ *   "nullable": false,
+ *   "arguments": [
+ *     {"name": "limit", "type": "Int", "nullable": false, "default": 10},
+ *     {"name": "offset", "type": "Int", "nullable": false, "default": 0}
+ *   ],
+ *   "sql_source": "v_user"
+ * }
+ * ```
+ */
+declare function Query(config?: OperationConfig): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Configuration for Mutation decorator.
+ */
+interface MutationConfig extends OperationConfig {
+    operation?: "CREATE" | "UPDATE" | "DELETE" | "CUSTOM";
+}
+/**
+ * Decorator to mark a function as a GraphQL mutation.
+ *
+ * This decorator registers the function with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @param config - Mutation configuration
+ * @returns Decorator function
+ *
+ * @example
+ * ```ts
+ * @Mutation({ sqlSource: "fn_create_user", operation: "CREATE" })
+ * function createUser(name: string, email: string): User {
+ *   pass;
+ * }
+ * ```
+ *
+ * This generates JSON:
+ * ```json
+ * {
+ *   "name": "createUser",
+ *   "return_type": "User",
+ *   "returns_list": false,
+ *   "nullable": false,
+ *   "arguments": [
+ *     {"name": "name", "type": "String", "nullable": false},
+ *     {"name": "email", "type": "String", "nullable": false}
+ *   ],
+ *   "sql_source": "fn_create_user",
+ *   "operation": "CREATE"
+ * }
+ * ```
+ */
+declare function Mutation(config?: MutationConfig): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Configuration for Enum decorator.
+ */
+interface EnumConfig {
+    description?: string;
+}
+/**
+ * Decorator to mark an object as a GraphQL enum.
+ *
+ * This decorator registers the enum with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @param values - Object with enum values as keys (values are not used, only keys matter)
+ * @param config - Optional configuration
+ * @returns Decorator function
+ *
+ * @example
+ * ```ts
+ * const OrderStatus = enum('OrderStatus', {
+ *   PENDING: 'pending',
+ *   SHIPPED: 'shipped',
+ *   DELIVERED: 'delivered'
+ * }, {
+ *   description: 'The status of an order'
+ * })
+ * ```
+ *
+ * This generates JSON:
+ * ```json
+ * {
+ *   "name": "OrderStatus",
+ *   "description": "The status of an order",
+ *   "values": [
+ *     {"name": "PENDING"},
+ *     {"name": "SHIPPED"},
+ *     {"name": "DELIVERED"}
+ *   ]
+ * }
+ * ```
+ */
+declare function enum_(name: string, values: Record<string, unknown>, config?: EnumConfig): Record<string, unknown>;
+/**
+ * Configuration for Interface decorator.
+ */
+interface InterfaceConfig {
+    description?: string;
+}
+/**
+ * Decorator to mark a class as a GraphQL interface.
+ *
+ * This decorator registers the interface with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * Interfaces define a common set of fields that multiple object types can implement.
+ * Per GraphQL spec §3.7, interfaces enable polymorphic queries.
+ *
+ * @param name - Interface name
+ * @param fields - Field definitions
+ * @param config - Optional configuration
+ * @returns Interface marker object
+ *
+ * @example
+ * ```ts
+ * const Node = interface('Node', {
+ *   id: { type: 'ID', nullable: false },
+ *   createdAt: { type: 'DateTime', nullable: false }
+ * }, {
+ *   description: 'An object with a globally unique ID'
+ * })
+ * ```
+ */
+declare function interface_(name: string, fields: Field[], config?: InterfaceConfig): Record<string, unknown>;
+/**
+ * Configuration for Union decorator.
+ */
+interface UnionConfig {
+    description?: string;
+}
+/**
+ * Decorator to mark a class as a GraphQL union type.
+ *
+ * Per GraphQL spec §3.10, unions represent a type that could be one of
+ * several object types. Unlike interfaces, unions don't define common fields.
+ *
+ * This decorator registers the union with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @param name - Union name
+ * @param memberTypes - List of member type names
+ * @param config - Optional configuration
+ * @returns Union marker object
+ *
+ * @example
+ * ```ts
+ * const SearchResult = union('SearchResult', ['User', 'Post', 'Comment'], {
+ *   description: 'Result of a search query'
+ * })
+ * ```
+ */
+declare function union(name: string, memberTypes: string[], config?: UnionConfig): Record<string, unknown>;
+/**
+ * Configuration for Input decorator.
+ */
+interface InputConfig {
+    description?: string;
+}
+/**
+ * Decorator to mark a class as a GraphQL input type.
+ *
+ * This decorator registers the input type with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @param name - Input type name
+ * @param fields - Field definitions with optional defaults
+ * @param config - Optional configuration
+ * @returns Input marker object
+ *
+ * @example
+ * ```ts
+ * const CreateUserInput = input('CreateUserInput', [
+ *   { name: 'name', type: 'String', nullable: false },
+ *   { name: 'email', type: 'String', nullable: false },
+ *   { name: 'role', type: 'String', nullable: false, default: 'user' }
+ * ], {
+ *   description: 'Input for creating a new user'
+ * })
+ * ```
+ */
+declare function input(name: string, fields: Array<Field & {
+    default?: unknown;
+}>, config?: InputConfig): Record<string, unknown>;
+/**
+ * Helper function to manually register type fields with metadata.
+ *
+ * Since TypeScript doesn't preserve type information at runtime by default,
+ * this helper allows explicit field registration for types.
+ *
+ * @param typeName - Name of the type
+ * @param fields - Field definitions
+ * @param description - Optional type description
+ *
+ * @example
+ * ```ts
+ * @Type()
+ * class User {
+ *   id: number;
+ *   name: string;
+ *   email: string | null;
+ * }
+ *
+ * registerTypeFields("User", [
+ *   { name: "id", type: "Int", nullable: false },
+ *   { name: "name", type: "String", nullable: false },
+ *   { name: "email", type: "String", nullable: true }
+ * ]);
+ * ```
+ */
+declare function registerTypeFields(typeName: string, fields: Field[], description?: string, options?: {
+    relay?: boolean;
+    sqlSource?: string;
+    jsonbColumn?: string;
+    isError?: boolean;
+    requiresRole?: string;
+    implements?: string[];
+    crud?: boolean | string[];
+    cascade?: boolean;
+}): void;
+/**
+ * Helper function to manually register query with full metadata.
+ *
+ * @param name - Query name
+ * @param returnType - Return type name
+ * @param returnsList - Whether query returns a list
+ * @param nullable - Whether result can be null
+ * @param args - Argument definitions
+ * @param description - Optional query description
+ * @param config - Additional configuration
+ *
+ * @example
+ * ```ts
+ * registerQuery(
+ *   "users",
+ *   "User",
+ *   true,
+ *   false,
+ *   [
+ *     { name: "limit", type: "Int", nullable: false, default: 10 },
+ *     { name: "offset", type: "Int", nullable: false, default: 0 }
+ *   ],
+ *   "Get list of users",
+ *   { sql_source: "v_user" }
+ * );
+ * ```
+ */
+declare function registerQuery(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+/**
+ * Helper function to manually register mutation with full metadata.
+ *
+ * @param name - Mutation name
+ * @param returnType - Return type name
+ * @param returnsList - Whether mutation returns a list
+ * @param nullable - Whether result can be null
+ * @param args - Argument definitions
+ * @param description - Optional mutation description
+ * @param config - Additional configuration
+ */
+declare function registerMutation(name: string, returnType: string, returnsList: boolean, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+/**
+ * Configuration for Subscription decorator.
+ */
+interface SubscriptionConfig {
+    entityType?: string;
+    topic?: string;
+    operation?: "CREATE" | "UPDATE" | "DELETE";
+    [key: string]: unknown;
+}
+/**
+ * Decorator to mark a function as a GraphQL subscription.
+ *
+ * This decorator registers the function with the schema registry for JSON export.
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * Subscriptions in FraiseQL are compiled projections of database events.
+ * They are sourced from LISTEN/NOTIFY or CDC, not resolver-based.
+ *
+ * @param config - Subscription configuration
+ * @returns Decorator function
+ *
+ * @example
+ * ```ts
+ * @Subscription({ topic: "order_events" })
+ * function orderCreated(userId?: string): Order {
+ *   pass;
+ * }
+ * ```
+ *
+ * This generates JSON:
+ * ```json
+ * {
+ *   "name": "orderCreated",
+ *   "entity_type": "Order",
+ *   "nullable": false,
+ *   "arguments": [
+ *     {"name": "userId", "type": "String", "nullable": true}
+ *   ],
+ *   "topic": "order_events"
+ * }
+ * ```
+ */
+declare function Subscription(config?: SubscriptionConfig): (_target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Helper function to manually register subscription with full metadata.
+ *
+ * @param name - Subscription name
+ * @param entityType - Entity type being subscribed to
+ * @param nullable - Whether result can be null
+ * @param args - Argument definitions (filters)
+ * @param description - Optional subscription description
+ * @param config - Additional configuration (topic, operation)
+ *
+ * @example
+ * ```ts
+ * registerSubscription(
+ *   "orderCreated",
+ *   "Order",
+ *   false,
+ *   [
+ *     { name: "userId", type: "String", nullable: true }
+ *   ],
+ *   "Subscribe to new orders",
+ *   { topic: "order_events", operation: "CREATE" }
+ * );
+ * ```
+ */
+declare function registerSubscription(name: string, entityType: string, nullable: boolean, args: ArgumentDefinition[], description?: string, config?: Record<string, unknown>): void;
+/**
+ * Decorator to register a custom scalar with the schema.
+ *
+ * This decorator registers the scalar globally so it can be:
+ * 1. Used in type annotations
+ * 2. Exported to schema.json
+ * 3. Validated at runtime
+ *
+ * @param target - CustomScalar subclass
+ * @returns The original class (unmodified)
+ * @throws If scalar name is not unique
+ * @throws If class doesn't extend CustomScalar
+ *
+ * @example
+ * ```typescript
+ * @Scalar()
+ * class Email extends CustomScalar {
+ *   name = "Email"
+ *
+ *   serialize(value: unknown): string {
+ *     return String(value)
+ *   }
+ *
+ *   parseValue(value: unknown): string {
+ *     const str = String(value)
+ *     if (!str.includes("@")) {
+ *       throw new Error("Invalid email")
+ *     }
+ *     return str
+ *   }
+ *
+ *   parseLiteral(ast: unknown): string {
+ *     if (ast && typeof ast === "object" && "value" in ast) {
+ *       return this.parseValue((ast as any).value)
+ *     }
+ *     throw new Error("Invalid email literal")
+ *   }
+ * }
+ *
+ * // Use in type:
+ * @Type()
+ * class User {
+ *   id: string
+ *   email: Email  // Uses registered Email scalar
+ *   name: string
+ * }
+ *
+ * // Export schema
+ * const schema = exportSchema("schema.json")
+ * // schema contains: "customScalars": {"Email": {...}}
+ * ```
+ *
+ * @remarks
+ * - Decorator returns class unmodified (no runtime FFI)
+ * - Registration is global (per-process)
+ * - Name must be unique within schema
+ * - Scalar must be defined before @Type that uses it
+ */
+declare function Scalar<T extends typeof CustomScalar>(target: T): T;
+
+/**
+ * CRUD operation generation for FraiseQL types.
+ *
+ * When `crud` is enabled on a type, this module auto-generates standard
+ * GraphQL queries (get-by-ID, list) and mutations (create, update, delete)
+ * following FraiseQL naming conventions.
+ */
+
+/**
+ * Generate CRUD queries and mutations for a type.
+ *
+ * @param typeName - The GraphQL type name (PascalCase)
+ * @param fields - The type's field definitions
+ * @param crud - `true` for all operations, or an array of specific operations
+ * @param sqlSource - Optional SQL source override (defaults to `v_{snake_name}`)
+ * @param cascade - Whether generated mutations include `cascade: true`
+ *
+ * @throws If `crud` contains unknown operation names
+ * @throws If the type has no fields
+ */
+declare function generateCrudOperations(typeName: string, fields: Field[], crud: boolean | string[], sqlSource?: string, cascade?: boolean): void;
+
+/**
+ * Schema export functionality for FraiseQL.
+ *
+ * This module provides functions to export the schema registry to JSON files
+ * that can be consumed by the fraiseql-cli compiler.
+ */
+
+/**
+ * Configuration helper for queries and mutations.
+ *
+ * This function is called inside decorated functions to specify SQL mapping
+ * and other configuration. The config is stored temporarily and applied by
+ * the decorator.
+ *
+ * @param config - Configuration options:
+ *   - sqlSource: SQL view name (queries) or function name (mutations)
+ *   - operation: Mutation operation type (CREATE, UPDATE, DELETE, CUSTOM)
+ *   - autoParams: Auto-parameter configuration (limit, offset, where, order_by)
+ *   - jsonbColumn: JSONB column name for flexible schemas
+ *
+ * @example
+ * ```ts
+ * @Query()
+ * function users(limit: number = 10) {
+ *   return config({
+ *     sqlSource: "v_user",
+ *     autoParams: { limit: true, offset: true, where: true }
+ *   });
+ * }
+ *
+ * @Mutation()
+ * function createUser(name: string, email: string) {
+ *   return config({
+ *     sqlSource: "fn_create_user",
+ *     operation: "CREATE"
+ *   });
+ * }
+ * ```
+ */
+declare function config(configObj: Record<string, unknown>): void;
+/**
+ * Export the schema registry to a JSON file.
+ *
+ * This function should be called after all decorators have been processed
+ * (typically at the end of the schema definition file).
+ *
+ * @param outputPath - Path to output schema.json file
+ * @param options - Export options
+ *
+ * @example
+ * ```ts
+ * // At end of schema.ts
+ * if (require.main === module) {
+ *   exportSchema("schema.json");
+ * }
+ * ```
+ *
+ * Notes:
+ * - Call this after all decorators have been applied
+ * - The output schema.json is consumed by fraiseql-cli
+ * - Pretty formatting is recommended for version control
+ */
+declare function exportSchema(outputPath: string, options?: {
+    pretty?: boolean;
+}): void;
+/**
+ * Get the current schema as a dictionary (without exporting to file).
+ *
+ * @returns Schema object with "types", "queries", and "mutations"
+ *
+ * @example
+ * ```ts
+ * const schema = getSchemaDict();
+ * console.log(schema.types);
+ * // [{ name: "User", fields: [...] }, ...]
+ * ```
+ */
+declare function getSchemaDict(): Schema;
+/**
+ * Export schema to a JSON string instead of a file.
+ *
+ * @param options - Export options
+ * @returns JSON string representation of the schema
+ *
+ * @example
+ * ```ts
+ * const jsonString = exportSchemaToString({ pretty: true });
+ * console.log(jsonString);
+ * ```
+ */
+declare function exportSchemaToString(options?: {
+    pretty?: boolean;
+}): string;
+/**
+ * Export ONLY types to a minimal types.json file (TOML-based workflow).
+ *
+ * This is the new minimal export function for the TOML-based configuration approach.
+ * It exports only the type definitions (types, enums, input_types, interfaces) without
+ * queries, mutations, federation, security, observers, or analytics metadata.
+ *
+ * All configuration moves to fraiseql.toml, which is merged with this types.json
+ * by the fraiseql-cli compile command.
+ *
+ * @param outputPath - Path to output types.json file
+ * @param options - Export options
+ *
+ * @example
+ * ```ts
+ * // At end of schema.ts
+ * if (require.main === module) {
+ *   exportTypes("user_types.json");
+ * }
+ * ```
+ *
+ * Notes:
+ * - Call this after all decorators have been applied
+ * - The output types.json contains only type definitions
+ * - Queries, mutations, and all configuration moves to fraiseql.toml
+ * - Use with: fraiseql compile fraiseql.toml --types user_types.json
+ */
+declare function exportTypes(outputPath: string, options?: {
+    pretty?: boolean;
+}): void;
+
+/**
+ * Validation engine for custom GraphQL scalars.
+ */
+
+/**
+ * Raised when custom scalar validation fails.
+ */
+declare class ScalarValidationError extends Error {
+    scalarName: string;
+    context: "serialize" | "parseValue" | "parseLiteral";
+    /**
+     * Creates a new ScalarValidationError.
+     *
+     * @param scalarName - Name of the scalar that failed validation
+     * @param context - The validation context ("serialize", "parseValue", or "parseLiteral")
+     * @param message - The underlying error message
+     */
+    constructor(scalarName: string, context: "serialize" | "parseValue" | "parseLiteral", message: string);
+}
+/**
+ * Execute validation for a custom scalar.
+ *
+ * @param scalarClass - The CustomScalar subclass to validate with
+ * @param value - The value to validate
+ * @param context - One of "serialize", "parseValue", or "parseLiteral"
+ * @returns The validated/converted value
+ * @throws ScalarValidationError if validation fails
+ * @throws Error if context is unknown
+ *
+ * @example
+ * ```typescript
+ * import { validateCustomScalar } from "fraiseql/validators"
+ * import { Email } from "./scalars"
+ *
+ * // Parse a variable value from GraphQL
+ * const emailValue = validateCustomScalar(Email, "user@example.com", "parseValue")
+ * // Returns "user@example.com"
+ *
+ * // Validation fails
+ * try {
+ *   validateCustomScalar(Email, "invalid-email", "parseValue")
+ * } catch (e) {
+ *   // ScalarValidationError: Scalar "Email" validation failed in parseValue: Invalid email
+ * }
+ * ```
+ */
+declare function validateCustomScalar(scalarClass: typeof CustomScalar, value: unknown, context?: "serialize" | "parseValue" | "parseLiteral"): unknown;
+/**
+ * Get all registered custom scalars.
+ *
+ * @returns Map of scalar names to CustomScalar classes
+ *
+ * @example
+ * ```typescript
+ * import { getAllCustomScalars } from "fraiseql/validators"
+ *
+ * const scalars = getAllCustomScalars()
+ * // Map { "Email" => class Email, "Phone" => class Phone, ... }
+ * ```
+ */
+declare function getAllCustomScalars(): Map<string, typeof CustomScalar>;
+
+/**
+ * Observer authoring API for FraiseQL event-driven workflows.
+ *
+ * Observers watch for database changes and trigger actions (webhooks, Slack, email).
+ * NO runtime behavior - only used for schema compilation.
+ *
+ * @example
+ * ```typescript
+ * import { Observer, webhook, slack } from "fraiseql";
+ *
+ * class Observers {
+ *   @Observer({ entity: "Order", event: "INSERT", actions: [webhook("https://...")] })
+ *   onOrderCreated() {}
+ * }
+ * ```
+ */
+
+/**
+ * Retry configuration for observer actions.
+ */
+type RetryConfig = ObserverRetryConfig;
+/**
+ * Default retry configuration used when no retry is specified.
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Configuration for the @Observer decorator.
+ */
+interface ObserverConfig {
+    entity: string;
+    event: string;
+    actions: ObserverAction[];
+    condition?: string;
+    retry?: RetryConfig;
+}
+/**
+ * Method decorator to register an observer with the schema registry.
+ *
+ * @param config - Observer configuration
+ * @returns Method decorator
+ */
+declare function Observer(config: ObserverConfig): (_target: any, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+/**
+ * Options for the webhook action factory.
+ */
+interface WebhookOptions {
+    url_env?: string;
+    headers?: Record<string, string>;
+    body_template?: string;
+}
+/**
+ * Create a webhook action.
+ *
+ * @param url - Static URL (mutually exclusive with url_env)
+ * @param options - Additional options including url_env, headers, body_template
+ * @returns Webhook action definition
+ * @throws If neither url nor url_env is provided
+ */
+declare function webhook(url?: string, options?: WebhookOptions): ObserverAction;
+/**
+ * Options for the slack action factory.
+ */
+interface SlackOptions {
+    webhook_url?: string;
+    webhook_url_env?: string;
+}
+/**
+ * Create a Slack notification action.
+ *
+ * @param channel - Slack channel (e.g. "#orders")
+ * @param message - Message template with {field} placeholders
+ * @param options - Optional webhook URL or environment variable override
+ * @returns Slack action definition
+ */
+declare function slack(channel: string, message: string, options?: SlackOptions): ObserverAction;
+/**
+ * Options for the email action factory.
+ */
+interface EmailOptions {
+    from_email?: string;
+}
+/**
+ * Create an email notification action.
+ *
+ * @param to - Recipient email address
+ * @param subject - Email subject template with {field} placeholders
+ * @param body - Email body template with {field} placeholders
+ * @param options - Optional sender override
+ * @returns Email action definition
+ */
+declare function email(to: string, subject: string, body: string, options?: EmailOptions): ObserverAction;
+
+/**
+ * Error hierarchy for FraiseQL HTTP client.
+ */
+declare class FraiseQLError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+interface GraphQLErrorEntry {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+declare class GraphQLError extends FraiseQLError {
+    readonly errors: GraphQLErrorEntry[];
+    constructor(errors: GraphQLErrorEntry[]);
+}
+declare class NetworkError extends FraiseQLError {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class TimeoutError extends NetworkError {
+    constructor(message?: string);
+}
+declare class AuthenticationError extends FraiseQLError {
+    readonly statusCode: 401 | 403;
+    constructor(statusCode: 401 | 403);
+}
+declare class RateLimitError extends FraiseQLError {
+    readonly retryAfterMs?: number;
+    constructor(retryAfterMs?: number);
+}
+
+/**
+ * Retry logic for FraiseQL HTTP client operations.
+ */
+
+interface HttpRetryConfig {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    retryOn?: Array<new (...args: never[]) => FraiseQLError>;
+    onRetry?: (attempt: number, error: FraiseQLError) => void;
+}
+declare function executeWithRetry<T>(fn: () => Promise<T>, config?: HttpRetryConfig): Promise<T>;
+
+/**
+ * FraiseQL HTTP client for executing GraphQL queries and mutations.
+ */
+
+interface FraiseQLClientConfig {
+    url: string;
+    authorization?: string | (() => string | Promise<string>);
+    timeoutMs?: number;
+    retry?: HttpRetryConfig;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+declare class FraiseQLClient {
+    private readonly url;
+    private readonly authorization?;
+    private readonly timeoutMs;
+    private readonly retry;
+    private readonly extraHeaders;
+    private readonly fetchFn;
+    constructor(urlOrConfig: string | FraiseQLClientConfig);
+    private resolveAuth;
+    private buildHeaders;
+    private executeRequest;
+    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>, operationName?: string): Promise<T>;
+    mutate<T = Record<string, unknown>>(mutation: string, variables?: Record<string, unknown>, operationName?: string): Promise<T>;
+}
+
+/**
+ * FraiseQL v2 - TypeScript Schema Authoring.
+ *
+ * This module provides decorators for defining GraphQL schemas that are compiled
+ * by the FraiseQL Rust engine. NO runtime FFI - decorators output JSON only.
+ *
+ * Architecture:
+ *   TypeScript @decorators → schema.json → fraiseql-cli → schema.compiled.json → Rust runtime
+ *
+ * @example
+ * ```typescript
+ * import * as fraiseql from "fraiseql";
+ *
+ * @fraiseql.Type()
+ * class User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * @fraiseql.Query({ sqlSource: "v_user" })
+ * function users(limit: number = 10): User[] {
+ *   // Function body not executed - only for type/metadata
+ * }
+ *
+ * // Export minimal types.json (use fraiseql.toml for queries, security, etc.)
+ * if (require.main === module) {
+ *   fraiseql.exportTypes("types.json");
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+declare const version = "2.0.0-alpha.1";
+
+export { type APIKey, type AirportCode, type ArgumentDefinition, type ArgumentInfo, AuthenticationError, type CIDR, type CUSIP, type Color, type ContainerNumber, type Coordinates, type CountryCode, type CurrencyCode, CustomScalar, DEFAULT_RETRY_CONFIG, type Date, type DateRange, type DateTime, type Decimal, type DomainName, type Duration, type Email, type EnumConfig, type EnumDefinition, type EnumValue, type ExchangeCode, type ExchangeRate, type Field, type FieldInfo, type FieldMetadata, type File, type FlightNumber, FraiseQLClient, type FraiseQLClientConfig, FraiseQLError, type FunctionSignature, GraphQLError, type GraphQLErrorEntry, type HTML, type HashSHA256, type Hostname, type HttpRetryConfig, type IBAN, type ID, type IPAddress, type IPv4, type IPv6, type ISIN, type Image, type InputConfig, type InputTypeDefinition, type InterfaceConfig, type InterfaceDefinition, type Json, type LEI, type LTree, type LanguageCode, type Latitude, type LicensePlate, type LocaleCode, type Longitude, type MACAddress, type MIC, type Markdown, type MimeType, type Money, Mutation, type MutationConfig, type MutationDefinition, NetworkError, Observer, type OperationConfig, type Percentage, type PhoneNumber, type Port, type PortCode, type PostalCode, Query, type QueryDefinition, RateLimitError, type RetryConfig, type ReturnTypeInfo, SCALAR_NAMES, type SEDOL, Scalar, ScalarValidationError, type Schema, SchemaRegistry, type SemanticVersion, type Slug, type StockSymbol, Subscription, type SubscriptionConfig, type SubscriptionDefinition, type Time, TimeoutError, type Timezone, type TrackingNumber, Type, type TypeConfig, type TypeDefinition, type URL, type UUID, type UnionConfig, type UnionDefinition, type VIN, type Vector, config, email, enum_, executeWithRetry, exportSchema, exportSchemaToString, exportTypes, extractFieldInfo, extractFunctionSignature, field, generateCrudOperations, getAllCustomScalars, getSchemaDict, input, interface_, isScalarType, registerMutation, registerQuery, registerSubscription, registerTypeFields, slack, typeToGraphQL, union, validateCustomScalar, version, webhook };