@stacksjs/types 0.70.88 → 0.70.90

package/dist/cloud.d.ts

@@ -0,0 +1,366 @@
+import type { ApiConfig } from './api';
+import type { FirewallConfig } from './security';
+declare interface SiteConfig {
+  domain: string
+  path: string
+}
+export declare interface TunnelCloudConfig {
+  enabled: boolean
+  domain?: string
+  region?: string
+  instanceType?: string
+  prefix?: string
+  ssl?: {
+    enabled: boolean
+    porkbunApiKey?: string
+    porkbunSecretKey?: string
+  }
+}
+export declare interface CloudOptions {
+  sites: {
+    root: string
+    path: string
+    [site: string]: string | SiteConfig
+  }
+  infrastructure: InfrastructureOptions
+  cdn: any
+  api: any
+  firewall: any
+}
+export type CountryCode = | 'AD'
+  | 'AE'
+  | 'AF'
+  | 'AG'
+  | 'AI'
+  | 'AL'
+  | 'AM'
+  | 'AO'
+  | 'AQ'
+  | 'AR'
+  | 'AS'
+  | 'AT'
+  | 'AU'
+  | 'AW'
+  | 'AX'
+  | 'AZ'
+  | 'BA'
+  | 'BB'
+  | 'BD'
+  | 'BE'
+  | 'BF'
+  | 'BG'
+  | 'BH'
+  | 'BI'
+  | 'BJ'
+  | 'BL'
+  | 'BM'
+  | 'BN'
+  | 'BO'
+  | 'BQ'
+  | 'BR'
+  | 'BS'
+  | 'BT'
+  | 'BV'
+  | 'BW'
+  | 'BY'
+  | 'BZ'
+  | 'CA'
+  | 'CC'
+  | 'CD'
+  | 'CF'
+  | 'CG'
+  | 'CH'
+  | 'CI'
+  | 'CK'
+  | 'CL'
+  | 'CM'
+  | 'CN'
+  | 'CO'
+  | 'CR'
+  | 'CU'
+  | 'CV'
+  | 'CW'
+  | 'CX'
+  | 'CY'
+  | 'CZ'
+  | 'DE'
+  | 'DJ'
+  | 'DK'
+  | 'DM'
+  | 'DO'
+  | 'DZ'
+  | 'EC'
+  | 'EE'
+  | 'EG'
+  | 'EH'
+  | 'ER'
+  | 'ES'
+  | 'ET'
+  | 'FI'
+  | 'FJ'
+  | 'FK'
+  | 'FM'
+  | 'FO'
+  | 'FR'
+  | 'GA'
+  | 'GB'
+  | 'GD'
+  | 'GE'
+  | 'GF'
+  | 'GG'
+  | 'GH'
+  | 'GI'
+  | 'GL'
+  | 'GM'
+  | 'GN'
+  | 'GP'
+  | 'GQ'
+  | 'GR'
+  | 'GS'
+  | 'GT'
+  | 'GU'
+  | 'GW'
+  | 'GY'
+  | 'HK'
+  | 'HM'
+  | 'HN'
+  | 'HR'
+  | 'HT'
+  | 'HU'
+  | 'ID'
+  | 'IE'
+  | 'IL'
+  | 'IM'
+  | 'IN'
+  | 'IO'
+  | 'IQ'
+  | 'IR'
+  | 'IS'
+  | 'IT'
+  | 'JE'
+  | 'JM'
+  | 'JO'
+  | 'JP'
+  | 'KE'
+  | 'KG'
+  | 'KH'
+  | 'KI'
+  | 'KM'
+  | 'KN'
+  | 'KP'
+  | 'KR'
+  | 'KW'
+  | 'KY'
+  | 'KZ'
+  | 'LA'
+  | 'LB'
+  | 'LC'
+  | 'LI'
+  | 'LK'
+  | 'LR'
+  | 'LS'
+  | 'LT'
+  | 'LU'
+  | 'LV'
+  | 'LY'
+  | 'MA'
+  | 'MC'
+  | 'MD'
+  | 'ME'
+  | 'MF'
+  | 'MG'
+  | 'MH'
+  | 'MK'
+  | 'ML'
+  | 'MM'
+  | 'MN'
+  | 'MO'
+  | 'MP'
+  | 'MQ'
+  | 'MR'
+  | 'MS'
+  | 'MT'
+  | 'MU'
+  | 'MV'
+  | 'MW'
+  | 'MX'
+  | 'MY'
+  | 'MZ'
+  | 'NA'
+  | 'NC'
+  | 'NE'
+  | 'NF'
+  | 'NG'
+  | 'NI'
+  | 'NL'
+  | 'NO'
+  | 'NP'
+  | 'NR'
+  | 'NU'
+  | 'NZ'
+  | 'OM'
+  | 'PA'
+  | 'PE'
+  | 'PF'
+  | 'PG'
+  | 'PH'
+  | 'PK'
+  | 'PL'
+  | 'PM'
+  | 'PN'
+  | 'PR'
+  | 'PS'
+  | 'PT'
+  | 'PW'
+  | 'PY'
+  | 'QA'
+  | 'RE'
+  | 'RO'
+  | 'RS'
+  | 'RU'
+  | 'RW'
+  | 'SA'
+  | 'SB'
+  | 'SC'
+  | 'SD'
+  | 'SE'
+  | 'SG'
+  | 'SH'
+  | 'SI'
+  | 'SJ'
+  | 'SK'
+  | 'SL'
+  | 'SM'
+  | 'SN'
+  | 'SO'
+  | 'SR'
+  | 'SS'
+  | 'ST'
+  | 'SV'
+  | 'SX'
+  | 'SY'
+  | 'SZ'
+  | 'TC'
+  | 'TD'
+  | 'TF'
+  | 'TG'
+  | 'TH'
+  | 'TJ'
+  | 'TK'
+  | 'TL'
+  | 'TM'
+  | 'TN'
+  | 'TO'
+  | 'TR'
+  | 'TT'
+  | 'TV'
+  | 'TW'
+  | 'TZ'
+  | 'UA'
+  | 'UG'
+  | 'UM'
+  | 'US'
+  | 'UY'
+  | 'UZ'
+  | 'VA'
+  | 'VC'
+  | 'VE'
+  | 'VG'
+  | 'VI'
+  | 'VN'
+  | 'VU'
+  | 'WF'
+  | 'WS'
+  | 'YE'
+  | 'YT'
+  | 'ZA'
+  | 'ZM'
+  | 'ZW';
+declare type Environment = 'development' | 'staging' | 'production';
+declare type InfrastructureOptions = Partial<{
+  type: 'serverless' // | 'server' coming soon
+  driver: 'aws'
+  api: ApiConfig
+  storage: object
+
+  /**
+   * **Firewall Settings**
+   *
+   * These settings are used to configure the firewall.
+   *
+   * @see https://stacksjs.com/docs/cloud#firewall
+   *
+   * @example
+   * ```ts
+   * firewall: {
+   *   enabled: true, // default: true
+   *   countryCodes: ['RU', 'IN'], // default: []
+   *   ipAddresses: ['56.123.456.789'], // default: []
+   *   queryString: ['foo', 'bar'], // default: []
+   *   httpHeaders: ['x-foo', 'x-bar'], // default: []
+   *   rateLimitPerMinute: 1000, // default: 1000
+   *   useIpReputationLists: true, // default: true
+   *   useKnownBadInputsRuleSet: true // default: true
+   * },
+   * ```
+   */
+  firewall: FirewallConfig
+
+  /**
+   * **Environments**
+   *
+   * These are the environments that your cloud will deploy.
+   *
+   * @example
+   * ```ts
+   * environments: ['production', 'staging', 'development']
+   * ```
+   */
+  environments: Environment[]
+
+  cdn: {
+    allowedMethods: 'GET_HEAD' | 'GET_HEAD_OPTIONS' | 'ALL'
+    cachedMethods: 'GET_HEAD' | 'GET_HEAD_OPTIONS'
+    minTtl: number
+    defaultTtl: number
+    maxTtl: number
+    compress: boolean
+    priceClass?: 'PriceClass_100' | 'PriceClass_200' | 'PriceClass_All'
+    originShieldRegion: string
+    cookieBehavior: 'none' | 'allowList' | 'all'
+
+    allowList: {
+      cookies: string[]
+      headers: string[]
+      queryStrings: string[]
+    }
+
+    realtimeLogs: {
+      enabled: boolean
+      samplingRate: number
+    }
+  }
+
+  ai: boolean
+  cli: boolean
+  docs: boolean
+  fileSystem: boolean
+
+  /**
+   * **Tunnel Configuration**
+   *
+   * Deploy a custom tunnel server for sharing local dev servers.
+   * Only needed for custom domains — localtunnel.dev is the shared default.
+   *
+   * @example
+   * ```ts
+   * tunnel: {
+   *   enabled: true,
+   *   domain: 'tunnel.mycompany.com',
+   *   ssl: { enabled: true },
+   * }
+   * ```
+   */
+  tunnel: TunnelCloudConfig
+}>;
+export type CloudConfig = Partial<CloudOptions>;

package/dist/cms.d.ts

@@ -0,0 +1,12 @@
+/**
+ * **CMS Options**
+ *
+ * Top-level feature gate plus any future CMS-wide settings. The CMS bundle
+ * (Post / Page / Author / Comment / Tag / Category models + edit dashboards)
+ * stays inert at boot when `enabled` is `false`.
+ */
+export declare interface CmsOptions {
+  enabled?: boolean
+  env?: string[]
+}
+export type CmsConfig = Partial<CmsOptions>;

package/dist/commerce.d.ts

@@ -0,0 +1,14 @@
+/**
+ * **Commerce Options**
+ *
+ * Top-level feature gate plus storefront defaults. The commerce bundle
+ * (Order / Cart / Product / Customer / Coupon / GiftCard / Shipping models +
+ * storefront API) stays inert at boot when `enabled` is `false`.
+ */
+export declare interface CommerceOptions {
+  enabled?: boolean
+  env?: string[]
+  currency?: string
+  defaultTaxRate?: number
+}
+export type CommerceConfig = Partial<CommerceOptions>;

package/dist/components.d.ts

@@ -0,0 +1,9 @@
+export declare interface TagOption {
+  name: string | string[]
+  description?: string
+  attributes?: {
+    name: string
+    description: string
+  }[]
+}
+export type TagsOptions = TagOption[];

package/dist/configure.d.ts

@@ -0,0 +1,12 @@
+export declare interface ConfigureOptions {
+  aws: boolean
+  profile: string
+  project: boolean
+  verbose: boolean
+  accessKeyId: string
+  secretAccessKey: string
+  region: string
+  output: string
+  quiet: boolean
+}
+export type ConfigureConfig = Partial<ConfigureOptions>;

package/dist/cors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CORS configuration types (stacksjs/stacks#1859 H-2).
+ *
+ * Lives in `@stacksjs/types` so userland `config/cors.ts` files can
+ * `import type { CorsConfig } from '@stacksjs/types'` and get full
+ * IntelliSense, and so the Cors middleware can read
+ * `config.cors` with proper typing instead of an `as any` cast.
+ */
+/**
+ * Raw CORS configuration — every field optional. Defaults fill in
+ * any field that's missing when the middleware resolves config.
+ *
+ * @example
+ * ```ts
+ * // config/cors.ts
+ * import type { CorsConfig } from '@stacksjs/types'
+ *
+ * export default {
+ *   origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   credentials: true,
+ *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *   allowedHeaders: ['Content-Type', 'Authorization', 'X-CSRF-Token'],
+ *   maxAge: 600,
+ * } satisfies CorsConfig
+ * ```
+ */
+export declare interface CorsConfig {
+  origin?: '*' | string[] | ((origin: string) => boolean)
+  methods?: string[]
+  allowedHeaders?: string[]
+  exposedHeaders?: string[]
+  credentials?: boolean
+  maxAge?: number
+}
+/**
+ * Resolved CORS configuration with all defaults applied. This is the
+ * shape the middleware passes through `applyCorsHeaders` /
+ * `buildPreflightResponse`.
+ */
+export declare interface ResolvedCorsConfig {
+  origin: '*' | string[] | ((origin: string) => boolean)
+  methods: string[]
+  allowedHeaders: string[]
+  exposedHeaders: string[]
+  credentials: boolean
+  maxAge: number
+}

package/dist/cron-jobs.d.ts

@@ -0,0 +1,61 @@
+import type { IntRange } from '@stacksjs/cron';
+export declare interface JitterConfig {
+  enabled: boolean
+  factor?: number
+  minDelay?: number
+  maxDelay?: number
+}
+export declare interface BackoffConfig {
+  strategy: BackoffStrategy
+  initialDelay: number
+  factor?: number
+  maxDelay?: number
+  jitter?: JitterConfig
+}
+export declare interface JobOptions {
+  name?: string
+  handle?: string | JobHandler
+  action?: string
+  description?: string
+  queue?: string
+  timezone?: string
+  tries?: IntRange<0, 185>
+  backoff?: number | number[]
+  backoffConfig?: BackoffConfig
+  rate?: string | Every
+  enabled?: boolean
+  timeout?: number
+  key?: string
+  ttl?: number
+  immediate?: boolean
+  meta?: Record<string, any>
+}
+export type Job = JobOptions;
+export type Jobs = Job[];
+export type CronJob = Job;
+export type CronJobs = Jobs;
+export type JobHandler = (_data?: any) => Promise<any> | any;
+/**
+ * Represents different backoff strategies for job retries
+ */
+declare type BackoffStrategy = 'fixed' | 'exponential' | 'linear' | 'random';
+export declare enum Every {
+  Second = '* * * * * *',
+  FiveSeconds = '*/5 * * * * *',
+  TenSeconds = '*/10 * * * * *',
+  ThirtySeconds = '*/30 * * * * *',
+  Minute = '* * * * *',
+  TwoMinutes = '*/2 * * * *',
+  FiveMinutes = '*/5 * * * *',
+  TenMinutes = '*/10 * * * *',
+  FifteenMinutes = '*/15 * * * *',
+  ThirtyMinutes = '*/30 * * * *',
+  Hour = '0 * * * *',
+  HalfHour = '0,30 * * * *',
+  Day = '0 0 * * *',
+  Week = '0 0 * * 0',
+  Weekday = '0 0 * * 1-5',
+  Weekend = '0 0 * * 0,6',
+  Month = '0 0 1 * *',
+  Year = '0 0 1 1 *',
+}

package/dist/dashboard.d.ts

@@ -0,0 +1,108 @@
+/**
+ * **Dashboard Options**
+ *
+ * Controls which sections render in the `buddy dev --dashboard` sidebar.
+ * Every section defaults to enabled — set a flag to `false` in
+ * `config/dashboard.ts` to hide it (for example, projects that don't
+ * use commerce features set `commerce.enabled: false`).
+ *
+ * The `data` section is always visible (it's where every project's
+ * userland models live). It exposes per-row toggles for the basic
+ * built-in rows so a project can drop, say, the newsletter Subscribers
+ * row when there's no newsletter without losing the model viewer.
+ */
+export declare interface DashboardOptions {
+  enabled?: boolean
+  env?: string[]
+  sections?: {
+    library?: { enabled?: boolean }
+    content?: { enabled?: boolean }
+    commerce?: { enabled?: boolean }
+    marketing?: { enabled?: boolean }
+    analytics?: { enabled?: boolean }
+    management?: { enabled?: boolean }
+    utilities?: { enabled?: boolean }
+    data?: {
+      dashboard?: { enabled?: boolean }
+      activity?: { enabled?: boolean }
+      users?: { enabled?: boolean }
+      teams?: { enabled?: boolean }
+      subscribers?: { enabled?: boolean }
+      allModels?: { enabled?: boolean }
+    }
+  }
+  ci?: {
+    enabled?: boolean
+    orgs?: string[]
+    runnerCaps?: Record<string, number>
+    runnerCapDefault?: number
+    ignoreRepos?: string[]
+    notifications?: {
+      enabled?: boolean
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      cooldownMinutes?: number
+    }
+    alerts?: {
+      enabled?: boolean
+      queuedThreshold?: number
+      windowMinutes?: number
+      channels?: Array<'email' | 'sms' | 'chat' | 'database'>
+      recipients?: Array<{ email?: string, phone?: string, userId?: number }>
+      retentionHours?: number
+    }
+  }
+}
+/**
+ * Per-model dashboard configuration (stacksjs/stacks#1843).
+ *
+ * Attach to a model definition to influence how the model surfaces in the
+ * dashboard sidebar without touching the framework's dashboard internals:
+ *
+ * ```ts
+ * defineModel({
+ *   name: 'AuditLog',
+ *   table: 'audit_logs',
+ *   dashboard: {
+ *     section: 'management',
+ *     icon: 'shield',
+ *     roles: ['admin'],
+ *     description: 'Append-only audit trail (admin-only)',
+ *   },
+ *   attributes: { … },
+ * })
+ * ```
+ *
+ * Resolution chain (most specific → fallback):
+ *
+ *   1. `dashboard.enabled === false` → model is hidden from the sidebar
+ *      entirely. The dynamic ORM viewer (`/models/<id>`) still works for
+ *      direct navigation, but the row is suppressed.
+ *   2. `dashboard.section` → pins the model to that section, overriding
+ *      the path-based auto-categorisation (commerce/, Content/, etc.).
+ *   3. `dashboard.label` / `dashboard.icon` → display overrides; fall back
+ *      to the model name and `iconMap` lookup.
+ *   4. `dashboard.roles` → role-gates the sidebar row. The server-side
+ *      sidebar builder emits the row with role metadata; the client filters
+ *      it out for users who lack a matching role. Permissive default
+ *      (unauthenticated viewers see everything — see `useRole.ts`).
+ */
+export declare interface DashboardModelOptions {
+  enabled?: boolean
+  label?: string
+  icon?: string
+  section?:
+    | 'home'
+    | 'library'
+    | 'content'
+    | 'commerce'
+    | 'marketing'
+    | 'analytics'
+    | 'management'
+    | 'utilities'
+    | 'data'
+    | 'app'
+  roles?: string[]
+  description?: string
+}
+export type DashboardConfig = Partial<DashboardOptions>;

package/dist/database.d.ts

@@ -0,0 +1,76 @@
+import type { SupportedDialect } from 'bun-query-builder';
+export declare interface DatabaseOptions {
+  default: SupportedDialect
+  logging?: boolean
+  connections: {
+    mysql?: {
+      url?: string
+      host?: string
+      port?: number
+      name?: string
+      username?: string
+      password?: string
+      prefix?: string
+    }
+    singlestore?: {
+      url?: string
+      host?: string
+      port?: number
+      name?: string
+      username?: string
+      password?: string
+      prefix?: string
+      ssl?: boolean
+    }
+    sqlite: {
+      url?: string
+      database?: string
+      prefix?: string
+    }
+    dynamodb?: {
+      key?: string
+      secret?: string
+      region?: string
+      prefix?: string
+      endpoint?: string
+    }
+    postgres?: {
+      url?: string
+      host?: string
+      port?: number
+      name?: string
+      username?: string
+      password?: string
+      prefix?: string
+    }
+  }
+  migrations: string
+  migrationLocks: string
+  safety?: {
+    confirmMigrate?: boolean
+    migrateFresh?: 'allow' | 'confirm' | 'disabled'
+  }
+  queryLogging?: {
+    enabled: boolean
+    slowThreshold: number
+    retention: number
+    pruneFrequency: number
+    excludedQueries?: string[]
+    analysis?: {
+      enabled: boolean
+      analyzeAll: boolean
+      explainPlan: boolean
+      suggestions: boolean
+    }
+  }
+}
+export declare interface FactoryOptions {
+  name: string
+  count?: number
+  items: object
+  columns: object
+}
+export declare interface SchemaOptions {
+  database: string
+}
+export type DatabaseConfig = Partial<DatabaseOptions>;