stacks-types

# Stacks Types ## Key Paths - Core types: `storage/framework/core/types/src/` - Generated types: `storage/framework/types/` - ORM globals: `storage/framework/types/orm-globals.d.ts` - Environment: `storage/framework/types/env.d.ts` - Actions: `storage/framework/types/actions.d.ts` (generated `ActionPath` union) - Model traits: `storage/framework/types/traits.d.ts` - Model attributes: `storage/framework/types/attributes.d.ts` - Events: `storage/framework/types/events.ts` - Attributes: `storage/framework/types/attributes.ts` ## Authentication Types (auth.ts) ```typescript interface AuthConfig { default: string guards: { [key: string]: { driver: 'session' | 'token', provider: string } } providers: { [key: string]: { driver: 'database', table: string } } username: string password: string tokenExpiry: number // 30 days tokenRotation?: number // deprecated; rotate explicitly defaultAbilities: string[] defaultTokenName: string } ``` ## ORM Global Types (orm-globals.d.ts) ```typescript // Full database row — model attributes + system fields + FK columns type ModelRow<T> = { id: number, uuid: string, created_at: string, updated_at: string } & ModelAttributes<T> // Insertable data — all fields optional type NewModelData<T> = Partial<ModelAttributes<T>> // Updateable data — all fields optional type UpdateModelData<T> = Partial<ModelAttributes<T>> // Model-aware request — narrows field names to model's attributes interface RequestInstance<TModel> { get(key: keyof TModel): any all(): TModel validate(): Promise<void> } ``` ## Environment Types (env.d.ts) ```typescript // Application APP_NAME, APP_ENV: 'local' | 'dev' | 'stage' | 'prod', APP_KEY, APP_URL, PORT, DEBUG // Database DB_CONNECTION: 'mysql' | 'sqlite' | 'postgres' | 'dynamodb' DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD // AWS AWS_ACCOUNT_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION // Mail MAIL_MAILER: 'smtp' | 'mailgun' | 'ses' | 'postmark' | 'sendmail' | 'log' MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_NAME, MAIL_FROM_ADDRESS // Search SEARCH_ENGINE_DRIVER: 'meilisearch' | 'algolia' | 'typesense' MEILISEARCH_HOST, MEILISEARCH_KEY // Frontend FRONTEND_APP_ENV: 'development' | 'staging' | 'production', FRONTEND_APP_URL ``` ## Event Types (events.ts) All model CRUD events: `model:created`, `model:updated`, `model:deleted` - **Content**: author, post, page - **Core**: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag - **Commerce (37 models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more All payloads are `Record<string, any>`. ## Billing Types (billing.ts) ```typescript interface TransactionHistory { id?, uuid?, name, description?, amount, type, provider_id?, user_id?, paymentmethod_id?, created_at, updated_at? } interface PaymentMethod { id?, uuid?, type, last_four, brand, exp_month, exp_year, is_default?, provider_id?, user_id? } interface Product { id?, uuid?, name, key, unit_price?, status?, image?, provider_id? } interface Subscription { id?, uuid?, type, provider_id, provider_status, provider_type, unit_price?, quantity?, trial_ends_at?, ends_at?, user_id? } ``` ## Attribute Types (attributes.ts) 200+ attribute definitions covering all models: | Category | Fields | |----------|--------| | Basic | name, slug, description, title, subject, content, body | | Dates | created_at, updated_at, published_at, scheduled_at, expires_at | | Commerce | unit_price, price, amount, tax_amount, discount_amount, total, currency | | User | email, password, phone, avatar, author_name, author_email | | Shipping | delivery_address, delivery_fee, region, countries | | Loyalty | loyalty_points_earned, loyalty_points_redeemed, points_required | | Analytics | views, conversions, clicks, reach, likes, shares | ## Request Types (traits.d.ts) Auto-generated per model: ```typescript interface PasskeysRequestType extends Request { get(key: 'id' | 'cred_public_key' | 'user_id' | 'counter' | ...): any } interface CommentablesRequestType extends Request { get(key: 'title' | 'body' | 'status' | 'commentables_id' | ...): any } ``` ## Auto-Imported Globals ### Framework Modules `Action`, `response`, `route`, `Router`, `schema`, `validate`, `slug`, `camelCase`, `pascalCase`, `snakeCase`, `kebabCase`, `titleCase`, `path`, `storage`, `log`, `handleError`, `Auth`, `register` ### 60+ ORM Models (globally available) User, Team, Post, Page, Author, Comment, Product, Order, Cart, Customer, Coupon, Category, Tag, Payment, Subscription, Driver, ShippingRate, GiftCard, LicenseKey, Job, FailedJob, Error, Log, Notification, and many more. ### stx components Components under `resources/components/` are resolved by the stx plugin and used directly in templates (`<Card />`) - no import, no global registration step. Editor metadata is generated into `storage/framework/core/web-types.json` and `custom-elements.json` by `buddy generate:web-types` / `generate:custom-data`. There is no `components.d.ts`. ### Actions Type ```typescript type ActionPath = 'Actions/LogAction' | 'Actions/HealthAction' | 'Actions/ExampleAction' | (string & {}) ``` ## CLI Types (cli.ts) ```typescript interface CliOptions { verbose?: boolean, silent?: boolean, quiet?: boolean cwd?: string, background?: boolean, timeoutMs?: number, project?: string } interface CleanOptions extends CliOptions {} interface CommitOptions extends CliOptions {} interface FreshOptions extends CliOptions { dryRun?: boolean } ``` ## Gotchas - **Types are auto-generated** — many files in `storage/framework/types/` are generated from model definitions - **ORM globals are truly global** — `ModelRow<T>`, `NewModelData<T>` available without imports - **RequestInstance is model-aware** — `.get()` and `.all()` narrowed to model's fields when typed - **Event payloads are untyped** — all `Record<string, any>`, not strongly typed per-model - **Env types augment Bun.env** — `Bun.env.DB_CONNECTION` is typed - **Attributes is a shared type** — 200+ fields covering ALL models, not per-model - **Router types auto-generated** — 130+ typed route definitions, regenerated when routes change - **Components.d.ts has 150+ entries** — globally registered, no imports needed